一、前言
作为一名后端，接口开发好了，与前端对接或者三方公司进行对接时，每次反反复复的依靠人力构建接口说明文档，每一次接口变更，输入输出结果字段变化，不胜其烦，能依据接口动态生成api对接文档岂不是更好，有变更，重新生成一下项目就好，还能在线调试接口，后端可控粒度高，你一定脑子里闪过Swagger，废话不多说，冲~
二、概述
Swagger作为一个Api文档生成和展示工具，能够依据一套OpenApi数据规范，自动的从系统中提取的注释信息，生成动态的生成Api说明文档，OpenApi规范本身是脱胎于Swagger；
Asp.Net Core中与之对应的类库分别为Swashbuckle，NSwag，参考链接：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio
Swashbuckle 有三个主要组成部分：
- Swashbuckle.AspNetCore.Swagger：将
SwaggerDocument对象公开为 JSON 终结点的 Swagger 对象模型和中间件。- Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成
SwaggerDocument对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。- Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具
NSwag
NSwag 提供了下列功能：
- 能够使用 Swagger UI 和 Swagger 生成器。
- 灵活的代码生成功能
借助
NSwag，无需使用现有API。也就是说，可使用包含Swagger的第三方API，并生成客户端实现。 使用NSwag，可以加快开发周期，并轻松适应API更改
三、基础应用
本章主要讲解Swashbuckle的基本使用技巧
3.1 开发环境
Windows10
Vs2019
Asp.Net Core 3.1 Web API
3.2 创建项目
选择项目模板为ASP.Net Core Web API项目名称为swaggertestbase，项目依赖的框架版本为.Net Core 3.1
3.3 引用类库包
Nuget包管理页面中的浏览页签，输入swagger进行搜索，找到截图中的对应类库Swashbuckle.AspNetCore.SwaggerGen
和Swashbuckle.AspNetCore.SwaggerUI，选择6.0.0，选择安装按钮即可，剩余无脑确定
安装成功后，引用中目录如下：
3.4 基础配置
引入命名空间
在Startup.cs中引入Swashbuckle.AspNetCore.SwaggerGen
using Swashbuckle.AspNetCore.SwaggerGen;
注册服务
在Startup.cs的ConfigureServices服务中注册服务
...... public void ConfigureServices(IServiceCollection services) { //注册服务 services.AddSwaggerGen(); services.AddControllers(); } ......
启用静态文件中间件
由于swagger-ui需要允许客户端访问服务端静态的样式和资源，所以需要服务配置函数Configure中路由中间件之前，启用静态中间件UseStaticFiles
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ..... //启动静态文件中间 app.UseStaticFiles(); ..... //启动路由中间件 app.UseRouting(); ..... }
配置Swagger中间件以及SwaggerUI中间件
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ..... //启动静态文件中间 app.UseStaticFiles(); #region Swagger中间件相关 //添加swagger配置，并启动中间件 app.UseSwagger(); //启用Swagger-ui中间件，并配置swagger json的请求终节点 app.UseSwaggerUI(); #endregion //启动路由中间件 app.UseRouting(); ..... }
启动项目
访问地址http://localhost:5000/swagger/v1/swagger.json，返回如下结果，标识默认对应Swagger Api Json结果如下：
{ "openapi": "3.0.1", "info": { "title": "swaggertestbase", "version": "1.0" }, "servers": [ { "url": "http://localhost:5000" } ], "paths": { "/WeatherForecast": { "get": { "tags": [ "WeatherForecast" ] } } } }
访问地址http://localhost:5000/swagger/index.html，访问结果如下：
以上为默认情况下，Swashbuckle基础的相关内容。
