开篇：
现在项目的开发一般都采用前后端分离的模式，后端同学完成开发后需要给前端的同学提供详细的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);