.NET Core利用swagger进行API接口文档管理的方法详解

一、问题背景

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

二、什么是swagger

swagger可以从不同的代码中，根据注释生成api信息，swagger拥有强大的社区，并且对于各种语言都支持良好，有很多的工具可以通过swagger生成的文件生成api文档

三、.net core中使用

.net core中使用首先要用nuget引用swashbuckle.aspnetcore，在startup.cs中加入如下代码

  // this method gets called by the runtime. use this method to add services to the container.
  public void configureservices(iservicecollection services)
  {
   services.addmvc();
   services.addswaggergen(c =>
   {
    c.swaggerdoc("v1", new info { title = "hello", version = "v1" });
    var basepath = platformservices.default.application.applicationbasepath;
    var xmlpath = path.combine(basepath, "webapplication2.xml");
    c.includexmlcomments(xmlpath);
   });
   services.addmvccore().addapiexplorer();
  }
  // this method gets called by the runtime. use this method to configure the http request pipeline.
  public void configure(iapplicationbuilder app, ihostingenvironment env)
  {
   if (env.isdevelopment())
   {
    app.usedeveloperexceptionpage();
   }
   app.usemvcwithdefaultroute();
   app.useswagger(c =>
   {
   });
   app.useswaggerui(c =>
   {
    c.showextensions();
    c.validatorurl(null);
    c.swaggerendpoint("/swagger/v1/swagger.json", "test v1");
   });
  }

以上部分为加载swagger的代码，位于startup.cs中，下面是controller代码：

using system;
using system.collections.generic;
using system.linq;
using system.threading.tasks;
using microsoft.aspnetcore.mvc;
namespace webapplication2.controllers
{
 /// <summary>
 /// 测试信息
 /// </summary>
 [route("api/[controller]/[action]")]
 public class valuescontroller : controller
 {
  /// <summary>
  /// 获取所有信息
  /// </summary>
  /// <returns></returns>
  [httpget]
  public ienumerable<string> get()
  {
   return new string[] { "value1", "value2" };
  }
  /// <summary>
  /// 根据id获取信息
  /// </summary>
  /// <param name="id"></param>
  /// <returns></returns>
  // get api/values/5
  [httpget("{id}")]
  public string get(int id)
  {
   return "value";
  }
  /// <summary>
  /// post了一个数据信息
  /// </summary>
  /// <param name="value"></param>
  // post api/values
  [httppost]
  public void post([frombody]string value)
  {
  }
  /// <summary>
  /// 根据id put 数据
  /// </summary>
  /// <param name="id"></param>
  /// <param name="value"></param>
  // put api/values/5
  [httpput("{id}")]
  public void put(int id, [frombody]string value)
  {
  }
  /// <summary>
  /// 根据id删除数据
  /// </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
  [httppost]
  public namevalue test(namevalue _info)
  {
   return _info;
  }
 }

 public class namevalue
 {
  /// <summary>
  /// name的信息
  /// </summary>
  public string name { get; set; }
  /// <summary>
  /// value的信息
  /// </summary>
  public string value { get; set; }
 }
}

接下来我们还需要在生成中勾上xml生成文档，如图所示

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

可以看到swagger将方法上的注释以及实体的注释都抓出来了，并且显示在swaggerui，整体一目了然，并且可以通过try it按钮进行简单的调试，但是在具体项目中，可能存在需要将某些客户端信息通过header带到服务中，例如token信息，用户信息等（我们项目中就需要header中带上token传递到后端），那针对于这种情况要如何实现呢？可以看下面的做法

// this method gets called by the runtime. use this method to add services to the container.
  public void configureservices(iservicecollection services)
  {
   services.addmvc();
   services.addswaggergen(c =>
   {
    c.swaggerdoc("v1", new info { title = "hello", version = "v1" });
    var basepath = platformservices.default.application.applicationbasepath;
    var xmlpath = path.combine(basepath, "webapplication2.xml");
    c.includexmlcomments(xmlpath);
    c.operationfilter<addauthtokenheaderparameter>();
   });
   services.addmvccore().addapiexplorer();
  }

 public class addauthtokenheaderparameter : ioperationfilter
 {
  public void apply(operation operation, operationfiltercontext context)
  {
   if (operation.parameters == null)
   {
    operation.parameters = new list<iparameter>();
   }
   operation.parameters.add(new nonbodyparameter()
   {
    name = "token",
    in = "header",
    type = "string",
    description = "token认证信息",
    required = true
   });
  }
 }

我们在configureservices添加了operationfilter<addauthtokenheaderparameter>() ，通过这种方式我们可以在swagger中显示token的header，并且进行调试（如图所示），addauthtokenheaderparameter 的apply的属性context中带了controller以及action的各种信息，可以配合实际情况使用

 四、与其他api管理工具结合

swagger强大的功能以及社区的力量，目前很多的api管理工具都支持yapi，目前我们使用的是由去哪儿开源的yapi，从图中可以看到yapi支持导入swagger生成的json文件，除该工具 之外doclever（开源）也是一个不错的api管理工具，也支持swagger文件导入（具体工具用法，大家可以去看他们的官网）

源码下载：demo地址

五、总结

swagger是一个很好的工具，并且在前后端分离开发越来越流行的情况下，在后续的开发过程中，我觉得会扮演着越来越重要的作用，目前我们公司小的项目已经准备开始使用swagger+yapi进行api的管理方式，而这篇文章也是这段时间抽空整理api管理的结果，希望可以帮助到大家，这里可能有很多不足的地方，欢迎大家拍砖，也希望可以跟大家一起进步

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，如果有疑问大家可以留言交流，谢谢大家对的支持。