在开发前后端分离的站点时，前端程序员需要后端的API说明才能进行相关的接口开发，传统的做法通常是写接口文档，这样后端程序员不但要开发还要写文档，如果API修改还得手动维护文档，这样就加大了后端程序员的工作量，有没有不写API文档的可能呢？Swagger就是解决这类问题的中间件。swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi，支持多语言跨平台。这篇文章讲述怎么在ASP.NET Core中添加Swagger中间件。.
一、环境准备
新建一个ASP.NET Core API站点，当然其他ASP.NET Core 也可以，用nuget手动添加Swagger的包Swashbuckle.AspNetCore，也可以用nuget命令行执行下面命令添加：
install-package Swashbuckle.AspNetCore并且分别添加三个Controller类，并在三个类中分别建一个get方法。
注：如果是.NET 5 以上版本默认是自带Swagger的，不用添加，并且已经配置好。
二、配置Swagger和Swagger分组
下面我们在Startup.cs下添加中间件和配置组件，二步完成基本的添加。
1、Startup.cs下ConfigureServices配置Swagger
默认配置很简单，只需要配置AddSwaggerGen就可以了。
services.AddSwaggerGen(c =>{c.SwaggerDoc("v1", new OpenApiInfo{ Title = "总的", Description = "", Version = "v1" });});
2、在Startup.cs下Configure代码中添加中间件
app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");});
这样就配置好了，点击浏览就可以看到你在站点写的接口了。
注：如果是.NET 5 以上版本默认不需要配置以上功能，已经配置好了。
3、配置Swagger分组
配置分组是3步，如下
a、在配置AddSwaggerGen下增加分组的设置，并且在DocInclusionPredicate控制输出哪些api。如下代码
services.AddSwaggerGen(c =>{//分三个组就需要配置3个SwaggerDoc，这里可以配置分组名称和介绍c.SwaggerDoc("v1", new OpenApiInfo { Title = "总的", Description = "", Version = "v1" });c.SwaggerDoc("group1", new OpenApiInfo { Title = "首页", Description = "", Version = "group1" });c.SwaggerDoc("group2", new OpenApiInfo { Title = "用户", Description = "", Version = "group2" });//c.DocInclusionPredicate((docname, b) => true);//这一步必不可少，通过反射出ApiExplorerSettingsAttribute特性的分组名称//否则分组没有效果，显示全部c.DocInclusionPredicate((docname, b) => {if (!b.TryGetMethodInfo(out MethodInfo methodInfo)) return false;var ver = methodInfo.DeclaringType.GetCustomAttributes(true).OfType<ApiExplorerSettingsAttribute>().Select(s=>s.GroupName);if (docname == "v1" && ver.FirstOrDefault() == null)return true;return ver.Any(v=>v.ToString()==docname);});});
b、在中间件中配置
app.UseSwagger();app.UseSwaggerUI(c =>{//同样配置三个Swagger终节点c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");c.SwaggerEndpoint("/swagger/group1/swagger.json", "group1");c.SwaggerEndpoint("/swagger/group2/swagger.json", "group2");});
c、在要分组的控制器中配置ApiExplorerSettings
[Route("api/[controller]")]//这里是分组名称[ApiExplorerSettings(GroupName = "group2")][ApiController]public class Test2Controller : ControllerBase{[HttpGet][Description("获取列表2")]public ActionResult Get(){return null;}}
通过这三步，到这里配置完成，效果如下：
总共分了三个组合，跟上面配置项一致。
如果大家感兴趣，可以把配置封装，然后配置的具体参数放到json文件里。
遇到的坑：特性的分组名称和配置的名称必须一致，并且是区分大小写的，否则失败
源码：https://pan.baidu.com/s/154yhyEQujORHehIKVY_WFQ?pwd=ffmn
提取码：ffmn
