ASP.NET API Versioning 8.1.0 版本中 Swagger.json 文件未找到问题解析

问题背景

在 ASP.NET Core 项目中，当开发者从 ASP.NET API Versioning 8.0.0 升级到 8.1.0 版本时，可能会遇到 Swagger UI 界面能够正常加载，但无法获取 swagger.json 文件的问题。具体表现为浏览器控制台显示 "Fetch error Not Found /swagger/v1/swagger.json" 错误。

问题现象

升级后，Swagger UI 界面能够正常显示，但在尝试获取 API 文档时失败。开发者观察到以下关键现象：

1. Swagger UI 界面可以正常加载
2. 浏览器控制台显示 404 错误，无法获取 swagger.json 文件
3. 应用程序日志中没有明显的错误信息
4. API 本身通过 Postman 等工具直接调用可以正常工作
5. 降级回 8.0.0 版本后问题消失

问题根源分析

经过深入排查，发现问题源于 Minimal API 端点配置中的 WithGroupName 方法调用。在 8.1.0 版本中，该方法与 API 版本控制的交互方式发生了变化，导致 Swagger 文档生成失败。

具体来说，当在 Minimal API 的路由组配置中同时使用：

1. API 版本控制（通过 NewApiVersionSet 和 WithApiVersionSet）
2. 自定义组名（通过 WithGroupName）

这两个功能在 8.1.0 版本中产生了冲突，导致 Swagger 文档生成器无法正确生成 API 文档。

解决方案

开发者发现以下两种解决方案：

方案一：移除 WithGroupName 调用

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

方案二：保留组名但调整配置顺序

如果确实需要保留组名功能，可以尝试调整配置顺序或检查 API 版本控制与组名的兼容性配置。

技术原理深入

这个问题实际上反映了 API 文档生成过程中的几个关键环节：

1. API 版本控制：通过 NewApiVersionSet 和 WithApiVersionSet 方法配置，为 API 添加版本支持
2. Swagger 文档生成：依赖正确的 API 分组信息来生成不同版本的文档
3. 组名冲突：自定义组名可能与 API 版本控制的默认分组机制产生冲突

在 8.0.0 版本中，这两个功能可能能够共存，但在 8.1.0 版本中，内部实现可能发生了变化，导致这种特定配置组合不再被支持。

最佳实践建议

1. 升级注意事项：在升级 API Versioning 库时，应特别注意与 Swagger 相关的配置
2. 配置审查：升级后应审查所有与 API 文档生成相关的配置
3. 测试策略：升级后应全面测试 API 文档生成功能，而不仅仅是 API 功能本身
4. 版本兼容性：关注库的发行说明，了解版本间可能的行为变化

总结

这个问题展示了 API 版本控制与文档生成工具之间复杂的交互关系。开发者在使用这些高级功能时，需要理解它们之间的依赖关系和可能的冲突点。通过这个案例，我们可以看到即使是看似简单的配置变更，也可能因为底层库的版本更新而产生意想不到的影响。

对于遇到类似问题的开发者，建议首先简化配置，逐步添加功能以定位问题根源，同时保持对库版本更新内容的关注，以便更好地理解和解决这类兼容性问题。