ASP.NET API Versioning 项目中 Swagger.json 文件未找到问题的分析与解决

问题背景

在 ASP.NET Core 项目中，当开发者使用 ASP.NET API Versioning 库进行 API 版本管理时，可能会遇到 Swagger UI 无法加载 swagger.json 文件的问题。具体表现为：升级到 8.1.0 版本后，Swagger 页面能够正常加载 index.html，但无法获取 swagger.json 文件，返回 "Not Found /swagger/v1/swagger.json" 错误。

问题现象

开发者在使用 8.0.0 版本时一切正常，但在升级到 8.1.0 版本后出现以下情况：

1. Swagger UI 页面能够正常加载
2. 页面显示 "Fetch error Not Found /swagger/v1/swagger.json"
3. 控制台无任何错误信息输出
4. API 本身通过 Postman 测试工作正常

配置分析

典型的 API Versioning 配置如下：

services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddMvc()
.AddApiExplorer(setup =>
{
    setup.GroupNameFormat = "'v'V";
    setup.SubstituteApiVersionInUrl = true;
})
.EnableApiVersionBinding();

Swagger 配置通常为：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    var descriptions = app.DescribeApiVersions();
    foreach (var description in descriptions)
    {
        c.SwaggerEndpoint(
            $"/swagger/{description.GroupName}/swagger.json",
            description.GroupName.ToUpperInvariant()
        );
    }
});

问题根源

经过排查，发现问题出在 Minimal API 的端点配置上。在 8.1.0 版本中，当使用 WithGroupName 方法为端点组指定名称时，会导致 Swagger 文档生成失败。

具体来说，以下代码片段中的 WithGroupName 调用是问题的根源：

var group = app.MapGroup(Routes.Personnel.MainUrl)
    .RequireAuthorization()
    .UseValidateOrganization(onlyOwner: false)
    .UseCheckMembership(needOrganizationInfo: true)
    .WithGroupName(Routes.Personnel.Group);  // 问题所在

解决方案

解决此问题的方法很简单：移除 WithGroupName 方法的调用即可。

修改后的代码应为：

var group = app.MapGroup(Routes.Personnel.MainUrl)
    .RequireAuthorization()
    .UseValidateOrganization(onlyOwner: false)
    .UseCheckMembership(needOrganizationInfo: true);

技术原理

在 ASP.NET API Versioning 8.1.0 版本中，WithGroupName 方法与 Swagger 文档生成机制存在兼容性问题。API Versioning 本身已经提供了版本分组机制，通过 GroupNameFormat 配置项（如 "'v'V"）自动为不同版本的 API 创建分组。手动指定组名可能会干扰这一机制。

最佳实践建议

1. 版本升级注意事项：在升级 API Versioning 版本时，应仔细测试 Swagger 集成部分，特别是文档生成功能。

2. 分组命名策略：优先使用 API Versioning 提供的自动分组机制，而非手动指定组名。

3. 调试技巧：当 Swagger 文档无法生成时，可以：

   • 逐步注释掉端点配置，定位问题端点
   • 检查控制台输出和调试窗口的异常信息
   • 确保所有端点都正确关联到版本组

4. Minimal API 配置：对于 Minimal API，确保版本集配置正确：

var apiVersionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .ReportApiVersions()
    .Build();

var versionedGroup = app.MapGroup($"api/v{version:apiVersion}")
    .WithApiVersionSet(apiVersionSet);

总结

ASP.NET API Versioning 是一个强大的 API 版本管理工具，但在与 Swagger 集成时可能会遇到文档生成问题。本文分析的案例展示了在 8.1.0 版本中 WithGroupName 方法导致的问题及解决方案。开发者在使用时应遵循官方推荐的分组策略，并在遇到问题时采用系统化的调试方法定位问题根源。