在 C#/.NET Core 的 Web API 中使用 Swagger 按模块和版本分组并实现排序

在 C#/.NET Core 的 Web API 中，Swagger 是一种用于生成和展示 API 文档的流行工具。通过使用 Swagger，我们可以更容易地理解和使用我们的 API。在复杂的项目中，往往需要按照模块和版本对 API 进行分组和排序，以便更好地管理和维护 API 文档。本文将介绍如何在 C#/.NET Core 的 Web API 中实现按模块和版本分组 Swagger。

1. 配置 Swagger 的基本步骤

首先，我们需要在项目中添加 Swagger 的支持。这可以通过 NuGet 包管理器来完成。执行以下命令来安装 Swashbuckle.AspNetCore 包：

dotnet add package Swashbuckle.AspNetCore

安装完成后，接下来需要在 Startup.cs 文件中进行配置。首先，在 ConfigureServices 方法中添加 Swagger 生成器：

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

    // 添加 Swagger 生成器
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1.0", new OpenApiInfo { Title = "My API", Version = "v1.0" });
        options.SwaggerDoc("v1.1", new OpenApiInfo { Title = "My API", Version = "v1.1" });
        // 更多版本可以继续添加
    });
}

在上面的代码中，我们定义了两个不同版本的 API 文档，分别是 v1.0 和 v1.1。

2. 创建 API 控制器并分组

我们可以通过使用 [ApiExplorerSettings] 特性来为控制器分组。以下是一个示例控制器，它属于 ModuleA 模块的 v1.0 版本：

using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.ModuleA
{
    [ApiExplorerSettings(GroupName = "v1.0")]
    [Route("api/v1.0/[controller]")]
    [ApiController]
    public class UsersController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetAllUsers()
        {
            return Ok(new string[] { "User1", "User2" });
        }
    }
}

另外，下面是一个属于 ModuleA 模块，但属于 v1.1 版本的控制器：

using Microsoft.AspNetCore.Mvc;

namespace MyApi.Controllers.ModuleA
{
    [ApiExplorerSettings(GroupName = "v1.1")]
    [Route("api/v1.1/[controller]")]
    [ApiController]
    public class UsersController : ControllerBase
    {
        [HttpGet]
        public IActionResult GetAllUsers()
        {
            return Ok(new string[] { "UserA", "UserB", "UserC" });
        }
    }
}

通过这种方式，我们可以根据不同的版本对 API 控制器进行分组，从而在 Swagger UI 中实现模块和版本的区分。

3. 配置 Swagger 文档的显示顺序

接下来，您可能希望根据一定顺序显示 Swagger 文档。这可以通过实现 IComparer 接口来排序分组。

首先，创建一个自定义的排序类：

public class SwaggerGroupSorter : IComparer<string>
{
    public int Compare(string x, string y)
    {
        // 自定义分组的顺序
        return string.Compare(x, y, StringComparison.Ordinal);
    }
}

然后在 Configure 方法中配置 Swagger UI，并使用我们的排序器：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 如果不是开发环境，则开启异常详细页面
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseRouting();

    // 启用 Swagger 中间件
    app.UseSwagger();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My API v1.0");
        options.SwaggerEndpoint("/swagger/v1.1/swagger.json", "My API v1.1");
        options.RoutePrefix = string.Empty; // 设置为根路径
    });

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

这样设置后，Swagger UI 会根据我们自定义的顺序显示 API 分组。

4. 结论

通过上述步骤，我们成功地在 C#/.NET Core 的 Web API 中实现了 Swagger 的模块和版本分组，以及自定义排序。这对于大型项目的 API 管理和维护具有重要意义，使开发者和用户可以更方便地了解和使用 API。希望这篇文章能对你在项目中的应用有所帮助。