再见了，Swagger：那么.ET 9如何重新定义API文档?

再见了，Swagger：那么.ET 9如何重新定义API文档?

随着.ET 9的即将发布，微软正在改变框架内API文档的处理方式。多年来一直包含在Web API模板中的广泛使用的API文档工具Swagger，将从.ET 9的初始Web API模板中移除。开发者将需要调整他们描述和可视化API端点的方式。那么，为什么会发生这种转变？对于.ET开发者来说，这意味着什么？

为什么微软移除Swagger？

微软宣布，标准Web API模板中的Swagger集成将被取消，原因是Swashbuckle缺乏持续维护。Swashbuckle.AspetCore包一直被广泛用于生成Swagger文档。而在.ET 9中，默认包含的是Microsoft.AspetCore.OpenApi库，这提供了一种直接从框架构建OpenAPI文档的标准化机制。

然而，与长期以来提供交互式界面以显示API端点的Swagger不同，Microsoft.AspetCore.OpenApi并没有自带用户界面。这意味着开发者如果想要获得API端点的可视化展示，则需要额外采取措施。

可以通过以下方式简单理解两者的区别：

• OpenAPI：一种规范
• Swagger：实现该规范的工具

虽然Microsoft.AspetCore.OpenApi提供了一种简单的方式来生成API文档，但习惯了Swagger美观界面的.ET用户可能需要探索其他替代方案。以下是几种选择：

1. 手动重新添加Swashbuckle 开发者如果喜欢Swagger的界面，仍然可以手动将Swashbuckle.AspetCore集成到.ET 9项目中。尽管这种方法保留了熟悉的体验，但需要额外的设置，而且由于该包缺乏活跃的维护，未来可能无法获得长期支持或升级。
2. 使用Swag Swag是Swagger的替代方案，提供类似的功能，并且目前仍在维护。Swag可以生成OpenAPI规范，并包括一个用于查看API端点的用户界面，使其成为.ET 9中Swagger的合适替代方案。
3. 使用Scalar和其他OpenAPI工具 Scalar及其他OpenAPI工具提供了强大的功能，用于创建和交互OpenAPI标准。虽然每种工具都有其独特优势，但在选择时需根据项目需求进行评估，例如设置的简便性、可维护性和功能集。
4. 构建自定义文档界面 使用Microsoft.AspetCore.OpenApi，开发者可以创建一个完全符合自身需求的文档界面。OpenApi库提供了对外观和功能的完全控制，适合需要高度定制的场景。

如何应对变化：开发者提示

许多开发者可能需要调整现有的工作流程以适应这一变化。以下是一些帮助你顺利过渡的建议：

提前规划

在迁移到.ET 9之前，了解项目需求并选择合适的文档工具，将有助于确保过渡顺利。可考虑OpenAPI、Swag或自定义解决方案，选择最适合团队需求的工具。

总结

在.ET 9中默认模板移除Swagger标志着整个.ET生态系统中API文档最佳实践的转变。尽管这一变化看似是一种退步，但它实际上为开发者如何记录和暴露API提供了更大的自由度和自定义空间。通过为项目选择最佳解决方案（如Swag、Swashbuckle或自定义界面），你仍然可以在.ET 9中提供清晰、直观的API文档。

译文：c-sharpcorner/article/goodbye-swagger-how-net-9-is-redefining-api-documentation/