ASP.NET Core Web API 教程中Swagger与OpenAPI的演进

在ASP.NET Core Web API开发中，API文档和测试工具的选择经历了从Swagger到OpenAPI的转变。这一变化对开发者，特别是初学者产生了直接影响。

从Swagger到OpenAPI的转变

早期版本的ASP.NET Core项目模板默认集成了Swashbuckle工具包，它提供了Swagger UI界面，开发者可以通过/swagger/index.html路径访问交互式API文档。但随着.NET 9的发布，微软转向了更标准的OpenAPI实现。

新的项目模板现在使用Microsoft.AspNetCore.OpenApi包来生成OpenAPI规范文档，而不是之前的Swashbuckle。这一变化带来了更轻量级、更标准化的API文档支持，但也意味着传统的Swagger UI不再默认可用。

对教程学习的影响

许多现有教程，包括官方文档中的"创建第一个Web API"教程，仍然基于旧的Swagger实现。当开发者按照这些教程操作时，会发现预期的/swagger/index.html路径返回404错误，导致无法继续后续的API测试步骤。

解决方案与替代方案

对于使用.NET 9及更高版本的项目，开发者有以下几种选择：

1. 继续使用Swagger UI：可以通过安装Microsoft.AspNetCore.OpenApi和Swashbuckle.AspNetCore包来恢复Swagger UI支持

2. 使用新的OpenAPI工具链：微软推荐使用符合OpenAPI标准的工具如Scalar等来查看和测试API

3. 使用Visual Studio内置的HTTP文件测试功能：这是另一种轻量级的API测试方案

最佳实践建议

对于新项目，建议采用新的OpenAPI标准实现。虽然初期学习曲线可能略高，但长期来看更符合行业标准和发展方向。同时，团队也正在更新相关教程文档，以反映这一技术变化。

这一转变体现了ASP.NET Core团队对开放标准和现代开发实践的承诺，虽然短期内可能造成一些适应成本，但长远来看将使API开发更加标准化和可持续。