ASP.NET Core 中使用 Swagger 实现 API 分组管理-CSDN博客

在 ASP.NET Core 开发中，组织和管理 API 文档是一个重要的环节。Swagger 是一个常用的工具，用于生成和展示 API 文档。通过使用 [ApiExplorerSettings] 和 [Tags] 特性，可以灵活地对 API 进行分组和组织，从而提高文档的可读性和易用性。本文将详细介绍如何使用这两种特性来实现 API 分组。

`[ApiExplorerSettings]` 实现版本分组

[ApiExplorerSettings] 特性用于将 API 操作分组到不同的版本。这在多版本 API 开发中非常有用，可以清晰地将不同版本的 API 分开显示。

1. 添加特性到控制器

首先，在控制器或操作方法上添加 [ApiExplorerSettings] 特性，并指定 GroupName。例如：

[ApiExplorerSettings(GroupName = "v1")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new[] { "value1", "value2" });
    }
}

2. 配置 Swagger

在 Startup.cs 或 Program.cs 中配置 Swagger，为每个版本生成一个文档。例如：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // 配置 API 探索器
    services.AddApiExplorer();

    // 配置 Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        options.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });

        // 根据 GroupName 匹配文档版本
        options.DocInclusionPredicate((docName, apiDesc) =>
        {
            return apiDesc.GroupName == docName;
        });
    });
}

3. 启用 Swagger UI

在 Configure 方法中启用 Swagger UI，并为每个版本指定一个文档端点。例如：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
        options.SwaggerEndpoint("/swagger/v2/swagger.json", "My API v2");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

4. 效果

启动应用后，访问 Swagger UI，你会看到两个文档选项：“My API v1” 和 “My API v2”。每个文档中只包含对应版本的 API 操作。

`[Tags]` 实现功能模块分组

[Tags] 特性用于将同一版本的 API 操作分组到不同的功能模块。这有助于在同一个版本中清晰地组织和展示不同的功能模块。

1. 添加特性到控制器

在控制器或操作方法上添加 [Tags] 特性，并指定模块名称。例如：

[Tags("Users")]
public class UsersController : ControllerBase
{
    [HttpGet]
    public IActionResult GetUsers()
    {
        return Ok(new[] { "user1", "user2" });
    }
}

2. 配置 Swagger

在 Startup.cs 或 Program.cs 中配置 Swagger，无需额外配置，因为 [Tags] 特性会自动被 Swagger 识别并用于分组。例如：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // 配置 Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

3. 启用 Swagger UI

在 Configure 方法中启用 Swagger UI。例如：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
    });

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}