app.UseSwagger(swaggerOptions => { //告诉OpenApi Json 信息请求拦截中间件，收到以下格式的请求时返回OpenApi Json信息 //注意：路径中必须包含: {documentName}，Swagger 中间件从请求路径中{documentName}占位符位置提取出api 文档名称，以便显示分组到该文档名称下的 //所有api信息。 swaggerOptions.RouteTemplate = "/BlogApis/{documentName}/swagger.json"; });
顺便提一下，通过查看Swagger 源码，我们可以看到默认的OpenApi Json解析路由就是 swagger/{documentName}/swagger.json ，这就是为什么我们一开始默认必须使用 /swagger/v1/swagger.json 格式去请求OpenApi Json 信息的原因。
上面我们在 OpenApi Json 请求地址的解析路由中提到了必须包含{documentName}参数，比如：/BlogApis/{documentName}/swagger.json,同时上面也提到了OpenApi Json 信息请求地址和这个路由是一一对应的，如：我们上面定义的OpenApi Json 信息的请求地址是：/BlogApis/v1/swagger.json，当浏览器访问SwaggerUI 页面并请求 /BlogApis/v1/swagger.json 地址时，根据路由模板：/BlogApis/{documentName}/swagger.json 从OpenApi Json 请求地址的第二段中提取出v1作为 api 文档名称，然后默认加载出所有 分组名称为 v1 或者 未定义分组名称的API 信息，并显示，那么我们如何通过documentName 对api 进行分组展示呢？
打开Startup.cs ,找到 ConfigureServices 方法，添加如下代码：
services.AddSwaggerGen(options => { //这里我们将用户相关的API分成一组,这里的User就是文档名称(documentName) options.SwaggerDoc("User", new Microsoft.OpenApi.Models.OpenApiInfo() { Title = "用户管理", Version = "1.0" }); //这里我们将文章管理相关的API分成一组。 options.SwaggerDoc("Post", new Microsoft.OpenApi.Models.OpenApiInfo() { Title = "文章管理", Version = "1.0" }); //以下是设置SwaggerUI中所有Web Api 的参数注释、返回值等信息从哪里获取。 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); options.IncludeXmlComments(xmlPath); });
找到Configure方法，按照如下配置：
app.UseSwaggerUI((options) => { //options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); //options.SwaggerEndpoint("/BlogApis/v1/swagger.json", "BlogApis"); //定义用户管理相关API的OpenApi Json 信息请求路径。 options.SwaggerEndpoint("/BlogApis/User/swagger.json", "UserManagerApis"); //定义文章管理相关API的OpenApi Json 信息请求路径。 options.SwaggerEndpoint("/BlogApis/User/swagger.json", "PostManagerApis"); });
分别在UserController 、 PostController 上面添加 [ApiExplorerSettings]特性，并设置分组名称
[Route("api/[controller]"), ApiExplorerSettings(GroupName = "User")] [ApiController] public class UserController : ControllerBase { /// <summary> /// 用户登录 /// </summary> /// <param>用户名</param> /// <param>密码</param> /// <returns></returns> [HttpPost] [ProducesResponseType(200, Type = typeof(UserInfo))] public UserInfo Login([FromForm] string userName, [FromForm] string password) { if (userName == "chenxin" && password == "123456") { return new UserInfo() { UserName = "chenxin", Age = 31 }; } return null; } [HttpGet] public List<UserInfo> GetAllUsers() { return new List<UserInfo>() { new UserInfo() { UserName="chenxin", Age=31 }, new UserInfo() { UserName="zhangsan", Age=35 } }; }
[Route("api/{controller}")] [ApiExplorerSettings(GroupName = "Post")] public class PostController : ControllerBase { /// <summary> /// 获取所有文章 /// </summary> /// <returns></returns> [HttpGet] public List<Post> GetAllPosts() { return new List<Post> { new Post() { Title="测试文章", Content="测试内容..." } }; } } public class Post { public string Title { get; set; } public string Content { get; set; } public DateTime PublishTime { get; set; } = DateTime.Now; }
按照上述步骤操作完成后，我们可以看到已经实现了API的分组。
好了，问题来了，为什么默认没有使用SwaggerDoc 方法定义任何文档名称默认也能找到API信息呢，其实还是Swagger 中间件默认给我们增加了一个名为v1的文档。
如果不想输入 swagger/index.html 来访问swaggerui ， 比如想改成 /BlogApisDocs,打开Startup.cs 找到 Configure 方法，添加如下代码：