ASP.NET Core Web API 为 Swagger 创建多个分组文档

ASP.NET Core Web API 为 Swagger 创建多个分组文档

一、效果展示

我们主要可以通过 AddSwaggerGen、SwaggerDoc、UseSwaggerUI、SwaggerEndpoint、ApiExplorerSettingsAttribute 这几个 API 进行相关的编辑，实现在右上角 Select a definition 处将内容展开为更多信息。

二、为控制器标记组别名称

首先，你需要为你的控制器 Controller 添加特性 ApiExplorerSettingsAttribute（[ApiExplorerSettings]）。
就像下面的代码一样：

    [ApiController]
    [Route("[controller]/[Action]")]
    [ApiExplorerSettings(GroupName = "hello")] // 注意这一句，其中 GroupName 的 "hello" 就是组别的名字
    public class HelloController:ControllerBase
    {
        [HttpGet]
        public string Test()
        {
            return "11";
        }
    }

三、在 Program.cs 初始化，为 builder 配置相关服务

你需要将本来的builder.Services.AddSwaggerGen(); 拓展为下面的内容：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("hello", new OpenApiInfo
    {
        Title = "你好！",
        Version = "v1",
        Description = "你好啊"
    });

    c.SwaggerDoc("weather-forecast", new OpenApiInfo
    {
        Title = "天气预报",
        Version = "v1",
        Description = "天气预报哦"
    });
});

四、在 Program.cs 初始化，为 app 配置文档关联

你可以app.UseSwaggerUI(); 拓展为：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/hello/swagger.json", "hello");
    c.SwaggerEndpoint("/swagger/weather-forecast/swagger.json", "weather-forecast");
});

五、其它

本文感谢 kimi ai 的一些指导。