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);
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，罗里吧嗦码了这些，文本粗糙，请多包涵，有问题欢迎指出，谢过！
