NetCore WebApi项目使用Swagger生成API交互文档

开篇：

　　现在项目的开发一般都采用前后端分离的模式，后端同学完成开发后需要给前端的同学提供详细的API接口文档说明，手动整理费事费力。那有没有解放双手的自动化工具呢？答案是肯定的。之前做.net webapi的时候使用的HelpPage来生成的API文档，到netcore这里，就是我们今天要分享的Swagger，它可以根据代码注释自动生成API描述文档，也可以通过配置生成交互式文档实现在线接口测试。

关于这个swagger大兄弟：

　　全称：Swashbuckle.AspNetCore，开源项目，git地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore

　　1.基本使用

　　　　1.1 安装依赖

　　　　1.2 startup配置

　　　　1.3 swagger启动配置

　　2.进阶使用

　　　　2.1 接口描述

　　　　2.2 返回类型描述

　　　　2.3 忽略不生成到API文档

　　　　2.4 api分组管理

　　　　2.5 多xml文档配置

　　3.扩展使用

　　　　3.1 全局信息添加（作者、联系人、许可信息等）

　　　　3.2 默认折叠配置

一、基本使用

　　1.1 安装Swagger依赖

　　第一种方式，程序包管理控制台：install-package Swashbuckle.AspNetCore

　　第二种方式，Nuget包管理中搜索 Swashbuckle.AspNetCore

　　1.2 startup配置

　　要使用swagger生成文档，我们需要在startup的ConfigureServices 和 Configure中对其进行中间件配置

在ConfigureServices中注册swagger生成器

1 // 注册swagger生成器，定义一个或多个文档，多个文档后边会讲到
2 services.AddSwaggerGen(c =>
3 {
4     c.SwaggerDoc("v1", new OpenApiInfo { Title = "曦昊-API说明文档", Version = "v1" });
5 });

在Configure中启用中间件配置

 // 启用中间件以将生成的 Swagger 公开为JSON终结点
 app.UseSwagger();
 // 启用swagger-ui 中间件，指定 Swagger JSON 终结点，以来公开交互式文档
 app.UseSwaggerUI(c =>
 {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API说明文档 V1");
 });

　　至此，swagger的基本配置完成，我们可以启动应用程序，输入/swagger访问看看啦

　　我们可以看到swagger已经自动帮我们生成了项目的api接口描述文档

　　1.3 swagger启动配置

　　完成上边的步骤后，我们已经可以启动浏览/swagger访问我们的Rest Apis文档了，但是每次启动再输入swagger也太麻烦了，接下来我们把swagger设置为我们的启动地址

　　文件：Properties - > launchSettings.json

　　将标注位置改为“swagger”

　　再次启动，直接进入了我们的swagger文档页面。

二、进阶使用

　　2.1 接口描述

　　上边已经提过swagger会根据我们的注释生成文档描述信息，但并不是我们添加了注释就可以的，想要swagger正常显示我们的备注信息，除了添加注释信息外，我们还要为swagger配置包含xml描述信息

　　首先按照我们平常的注释方式为接口添加注释

　　其次，为我们的项目配置输出xml文件（项目右键--属性--生成--输出）

　　最后在startup的ConfigureServices中配置swagger包含xml描述信息

    // 配置从xml文档中获取描述信息
    // 路径我们获取的项目路径+startup命名空间（也可以直接写生成的xml名称）
    var filePath = Path.Combine(System.AppContext.BaseDirectory, typeof(Startup).Assembly.GetName().Name + ".xml");
    c.IncludeXmlComments(filePath);

View Code

　　ok，现在我们启动调试进入swaggerUI，我们会看到swagger已经显示出了我们自定义的注释信息

　　2.2 返回类型描述

　　当我们写的接口已IActionResult为返回类型的时候，我们会发现swagger的Responses下并没有为我们生成返回信息描述，因为它并不知道我们具体要返回的是什么形式的数据

　　例如，我们新写一个分页接口：

　　我们可以看到没有任何的返回信息描述，那怎么办呢？这里我们就要用到swagger的ProducesResponseType特性来告诉swagger我们的返回结构

　　再次启动调试，我们发现在Responses这一模块已经正确显示了我们的PageList描述信息。

　　细心的可能会发现我们在使用ProducesResponseType的时候除了给了它一个type，还给了一个200，这是啥意思呢？

　　这个200的意思就是响应状态200的时候我给你返回这么一个结构的数据，那是不是说我们可以定义不同响应状态不同数据结构呢？答案是肯定的。ProducesResponseType是可以多次标记的，你只需要为其他状态按照上边的方式添加返回结构标记即可

　　2.3 忽略不生成到API文档

　　有些时候我们需要向文档的阅读者隐藏部分的接口信息，这个时候我们就会用到ApiExplorerSettings特性

　　在我们需要隐藏的接口标记 [ApiExplorerSettings(IgnoreApi = true)] 即可

　　2.4 api分组管理

　　当我们的接口过多想要拆分显示，或我们根据不同大类进行区分（系统操作、业务操作...），或我们要分多个版本等等，我们就需要用到分组这个操作，实际上分组就是为swagger生成多个文档，上操作：

　　第一步，为swagger添加一个新的文档（startup -- > ConfigureServices）

　第二步，为swagger添加一个对应的json终结点

　　第三步，为控制器或action方法添加标记 [ApiExplorerSettings(GroupName = "v2")] ，groupName设置的是要在哪一组中显示，这里是区分大小写的，要跟上述设置中保持一致

　　然后就可以在swagegrUI界面的右上角切换不同的文档了

　　2.5 多xml文档配置

　　常用场景：跨程序集显示注释信息

　　swagger我们默认配置的是加载当前程序生成的xml，我们只需要为为其它程序集配置输出xml，并在services.AddSwaggerGen中配置加载改xml文件即可

　　例如：

　但是，如果有多个程序集需要配置，这里是不是会有很多的配置项，并且每加一个程序集我们就要写一遍，即不方便又造成代码的臃肿。ok，接下来我们进行一下改版

　　首先，我们把所有的xml生成到一个目录下，比如当前应用根目录的docs:

　　然后我们在swagger设置xml文档的地方改为以下方式　　

    // 获取自定义的xml目录   
    var xmlPath = Path.Combine(System.AppContext.BaseDirectory, "Docs");
    DirectoryInfo dir = new DirectoryInfo(xmlPath);
    // 获取目录下的所有xml文件，并设置为swagger文档包含文件
    dir.GetFiles("*.xml").ToList().ForEach(u =>
    {
         c.IncludeXmlComments(u.FullName, true);
    })

　　ok，再次启动程序，我们会发现，XH.Core下Model对象的描述信息也有了~

三、扩展使用

　　3.1 全局信息添加（作者、联系人、许可信息等）

　　这些信息的配置是在services.AddSwaggerGen下进行配置，如下：

　　运行程序，显示如下

　　3.2 默认折叠配置

　　当接口慢慢变多，你想进入swagger页面后能非常清晰的浏览controller级目录，你会需要这个配置　　

    app.UseSwaggerUI(c =>
    {
         c.SwaggerEndpoint("/swagger/v1/swagger.json", "API说明文档 V1");
         c.SwaggerEndpoint("/swagger/v2/swagger.json", "API说明文档 V2");
         c.DocExpansion(DocExpansion.None); // 全部折叠
    });

　　如果想隐藏掉Schemas,使用 c.DefaultModelsExpandDepth(-1) 设置即可，位置同上

　　ok，罗里吧嗦码了这些，文本粗糙，请多包涵，有问题欢迎指出，谢过！