净核心利用时髦的进行应用程序接口接口文档管理的方法详解

一、问题背景

随着技术的发展，现在的开发模式已经更多的转向了前后端分离的模式，在前后端开发的过程中，联系的方式也变成了应用程序接口接口，但是目前项目中对于应用程序接口的管理很多时候还是通过手工编写文档，每次的需求变更只要涉及到接口的变更，文档都需要进行额外的维护，如果有哪个小伙伴忘记维护，很多时候就会造成一连续的问题，那如何可以更方便的解决应用程序接口的沟通问题？时髦的给我们提供了一个方式，由于目前主要我是投入在。净核心项目的开发中，所以以。净核心作为示例

二、什么是时髦的

时髦的可以从不同的代码中，根据注释生成应用程序接口信息史瓦格拥有强大的社区，并且对于各种语言都支持良好，有很多的工具可以通过时髦的生成的文件生成应用程序接口文档

三、净核心中使用。净核心中使用首先要用框架引用Swashbuckle .AspNetCore，在startup.cs中加入如下代码

//运行时调用此方法。使用此方法向容器添加服务public void ConfigureServices(IServiceCollection services){ services .AddMvc()；服务AddSwaggerGen(c={ c . SwaggerDoc(' v1 '，新信息{ Title='Hello '，Version=' v1 ' })；var basePath=PlatformServices .默认值申请。应用程序基本路径；var xmlPath=路径组合(基本路径，'网络应用2。XML ')；c . includexcmments(XMlpath)；});服务AddMvcCore().AddApiExplorer()；} //此方法由运行时调用。使用此方法配置超文本传送协议请求管道公共空间配置(IApplicationBuilder)应用程序，ihostingenvirmentenv){ if(env .IsDevelopment()) { app .usedeveloper异常页()；}应用程序.usemvcwithdedfaultroute()；应用程序.useswaggle(c={ })；应用程序.UseSwaggerUI(c={ c . ShowExtensions()；c . ValidatorUrl(null)；c . SwaggerEndpoint('/swag/v1/swag。JSON '，'测试V1 '；});}以上部分为加载时髦的的代码，位于startup.cs中，下面是控制器代码：

使用系统；使用系统。集合。通用；使用系统Linq .使用系统。线程化。任务；使用微软AspNetCore。手动音量调节命名空间网络应用2 .控制器{ ///摘要///测试信息////摘要[路由(' API/[控制器]/[动作]')]公共类值控制器：控制器{///摘要///获取所有信息////summary///returns/returns[HttpGet]public ienumerablesting Get(){ return new string[]{ ' value 1 '，' value 2 ' }；} ///摘要///根据身份获取信息////summary////param name=' id '/param////returns/returns//GET API/values/5[HttpGet(' { id } ')]公共字符串GET(int id){返回值'；} ///摘要///POST了一个数据信息////summary////param name=' value '/param///POST API/values[httpset]public void POST([FromBody]字符串值){ } ///summary //根据身份证号码数据////summary////param name=' id '/param///param name=' value '/param///PUT API/values/5[Httput(' { id } ')]public void PUT(int id，[FromBody]字符串值){ } ///summary //根据身份删除数据////summary///param name=' id '/param//DELETE API/values/5[HttpDelete(' { id } ')]public void DELETE(int id){ }///summary///复杂数据操作////summary////param name=' id '/param///DELETE API/values/5[HttpTest]public name value test(name value _ info){ return _ info；} }公共类名值{///summary///name的信息////摘要公共字符串名称{获取设置；} ///summary ///value的信息////摘要公共线值{获取设置；} }}接下来我们还需要在生成中勾上可扩展置标语言生成文档，如图所示

接下去我们可以运行起来了，调试，浏览器中输入http://localhost :50510/swag/这里端口啥的根据实际情况来，运行效果如下图所示：

可以看到，swag已经抓取了对方法和实体的评论，并在swaggerui中显示出来，通过try it按钮可以轻松调试。但是在具体的项目中，有些客户端信息可能需要通过header带到服务中，比如token信息和用户信息(在我们的项目中，我们需要将token带入header并传递到后端)，那么这种情况如何实现呢？您可以看到以下实践

//运行时调用此方法。使用此方法向容器添加服务。public void ConfigureServices(IServiceCollection services){ services。AddMvc()；服务。AddSwaggerGen(c={ c . SwaggerDoc(' v1 '，new Info { Title='Hello '，Version=' v1 ' })；var basePath=PlatformServices。默认值。application . application base path；var xmlPath=路径。Combine(basePath，' Webapplication 2 . XML ')；c . includexlcomments(XMlpath)；c . OperationFilterAddAuthTokenHeaderParameter()；});服务。AddMvcCore()。AddApiExplorer()；}公共类AddAuthTokenHeaderParameter : iooperationfilter { public void Apply(Operation Operation，OperationFilterContext){ if(Operation。参数==null) {操作。参数=新的ListIParameter()；} operation . parameters . add(new nonbodyparameter(){ name=' token '，in=' header '，type=' string '，description=' token authentication information '，Required=true })；}}我们在ConfigureServices中添加了OperationFilterAddAuthtokenheader参数()。这样，我们就可以在way中显示Token的头部并进行调试(如图所示)。AddAuthTokenHeaderParameter应用的属性上下文携带了控制器和动作的各种信息，可以根据实际情况使用。

四.与其他应用编程接口管理工具的集成

目前很多API管理工具支持y API是因为Swagger强大的功能和社区的实力。目前，我们使用的是从去哪儿开源的YApi。从图中我们可以看到，YApi支持导入swag生成的JSON文件。除了这个工具之外，DOClever也是一个不错的API管理工具，它也支持导入swagger文件(具体工具用法，可以查看他们的官网)

源代码下载：演示地址

动词（verb的缩写）摘要

swag是一个很好的工具，在前端分离开发越来越普及的情况下，它将在后续的开发过程中发挥越来越重要的作用。目前我公司的小项目准备开始使用swagger yapi进行api管理，这篇文章也是抽出时间整理这段时间API管理的结果，希望对大家有所帮助。这里可能有很多缺点。欢迎拍砖，希望和大家一起进步。

以上就是本文的全部内容。希望本文的内容对大家的学习或工作有一定的参考价值。有问题可以留言交流。谢谢你的支持。