• 为什么微软要在.NET 9中移除Swagger ?
  • 发布于 1个月前
  • 97 热度
    0 评论
  • 太伤人
  • 1 粉丝 42 篇博客
  •   
随着.NET 9的即将发布,微软正在改变框架内API文档的处理方式。多年来一直包含在Web API模板中的广泛使用的API文档工具Swagger,将从.NET 9的初始Web API模板中移除。开发者将需要调整他们描述和可视化API端点的方式。那么,为什么会发生这种转变?对于.NET开发者来说,这意味着什么?

为什么微软移除Swagger?
微软宣布,标准Web API模板中的Swagger集成将被取消,原因是Swashbuckle缺乏持续维护。Swashbuckle.AspNetCore包一直被广泛用于生成Swagger文档。而在.NET 9中,默认包含的是Microsoft.AspNetCore.OpenApi库,这提供了一种直接从框架构建OpenAPI文档的标准化机制。然而,与长期以来提供交互式界面以显示API端点的Swagger不同,Microsoft.AspNetCore.OpenApi并没有自带用户界面。这意味着开发者如果想要获得API端点的可视化展示,则需要额外采取措施。

可以通过以下方式简单理解两者的区别:
OpenAPI:一种规范

Swagger:实现该规范的工具


.NET 9中API文档的选项有哪些?
虽然Microsoft.AspNetCore.OpenApi提供了一种简单的方式来生成API文档,但习惯了Swagger美观界面的.NET用户可能需要探索其他替代方案。以下是几种选择:

手动重新添加Swashbuckle
开发者如果喜欢Swagger的界面,仍然可以手动将Swashbuckle.AspNetCore集成到.NET 9项目中。尽管这种方法保留了熟悉的体验,但需要额外的设置,而且由于该包缺乏活跃的维护,未来可能无法获得长期支持或升级。

使用NSwag
NSwag是Swagger的替代方案,提供类似的功能,并且目前仍在维护。NSwag可以生成OpenAPI规范,并包括一个用于查看API端点的用户界面,使其成为.NET 9中Swagger的合适替代方案。

使用Scalar和其他OpenAPI工具
Scalar及其他OpenAPI工具提供了强大的功能,用于创建和交互OpenAPI标准。虽然每种工具都有其独特优势,但在选择时需根据项目需求进行评估,例如设置的简便性、可维护性和功能集。

构建自定义文档界面
使用Microsoft.AspNetCore.OpenApi,开发者可以创建一个完全符合自身需求的文档界面。OpenApi库提供了对外观和功能的完全控制,适合需要高度定制的场景。

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

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

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