微软决定从 .NET 9 中删除内置的 Swagger 支持

Microsoft 决定从 .NET 9 中删除内置的 Swagger 支持,主要原因是为了简化框架并提高其模块化和灵活性。以下是几个关键原因:

精简框架核心:Microsoft 希望保持 .NET 核心的轻量化,减少内置工具的数量,把 .NET 平台的功能模块化。将 Swagger 支持从核心库中移除,可以让框架更加灵活,使得开发者可以按需选择不同的第三方库,而不是被固定到一个内置的工具上。

鼓励开源社区发展:Swagger 和 OpenAPI 社区有众多开源工具,例如 Swashbuckle 和 NSwag,Microsoft 期望更多依赖开源的力量,以加快开发与更新速度。通过第三方包,社区的更新可以更快速地反映在 Swagger 支持上,不需要等待 .NET 框架的发布周期。

减少维护负担:内置的 Swagger 支持意味着 Microsoft 需要持续投入资源去维护和更新,而第三方工具提供相同的功能后,微软可以将更多精力集中在框架的核心改进上。

避免冗余的实现:.NET 社区对 Swagger 的需求可以由 Swashbuckle、NSwag 等工具灵活支持,并且这些工具通常提供更多自定义选项和更丰富的功能,不需要 .NET 内部来重写一个支持。

Microsoft 希望 .NET 核心保持精简,并把生态系统中的功能通过社区支持的库来扩展。这样不仅能让开发者有更多选择,还能提升框架整体的更新灵活性。

有哪些可以代替Swagger的工具?

除了 Swagger(现在称为 OpenAPI)本身,还有许多替代的包或库可用于生成 API 文档,提供自动化的客户端代码生成等功能。以下是一些可以替代 Swagger 的常用包:

1. NSwag

功能:NSwag 是一个开源的 Swagger/OpenAPI 工具包,专为 .NET 开发者设计。

特点:支持生成客户端代码(C# 和 TypeScript),可以从 OpenAPI 文档生成 API 控制器。

适用场景:适合 .NET 项目,尤其适合希望在生成文档的同时,还需要生成类型安全的客户端代码的项目。

2. ReDoc

功能:ReDoc 是一个开源工具,用于将 OpenAPI(Swagger)文档转换成静态、优雅的 HTML 文档。

特点:文档界面美观,支持 Markdown 格式的文档注释,支持 OpenAPI 3。

适用场景:适合需要对外展示 API 文档,且对文档外观和用户体验有较高要求的项目。

3. Apiary(基于 API Blueprint)

功能:Apiary 提供了基于 API Blueprint 的文档生成、模拟和测试功能。

特点:支持 API Mocking 和协作功能,可以快速创建 API 文档原型,方便前后端协作。

适用场景:适合需要快速原型和文档,并且希望通过文档模拟来测试 API 的项目。

4. RAML(RESTful API Modeling Language)

功能:RAML 是一种与 OpenAPI 类似的 API 描述语言,允许开发者定义和记录 RESTful API。

特点:专注于 API 设计和建模,格式易读易写,且支持多种文档生成工具。

适用场景:适合想要使用非 OpenAPI 标准来定义 API,并希望与 MuleSoft 生态系统整合的开发者。

5. FastAPI(Python)

功能:FastAPI 是一个用于构建高性能 API 的 Python 框架,支持自动生成 OpenAPI 和 JSON Schema 文档。

特点:内置自动文档生成,支持 Swagger UI 和 ReDoc 的展示,极简的 API 定义方式。

适用场景:适合使用 Python 进行高性能 API 开发的项目,尤其是需要快速生成 API 文档的情况。

6. GraphQL + Apollo

功能:GraphQL 是一种用于构建和查询 API 的数据查询语言,Apollo 则是一个流行的 GraphQL 生态库。

特点:动态查询文档,不需要单独的文档生成工具;通过 Apollo Studio 提供文档、监控和协作支持。

适用场景:适合需要灵活数据查询结构、动态文档的项目,尤其是在前后端协作频繁的场景中。

7. Slate

功能:Slate 是一个用于生成静态 API 文档的工具。

特点:使用 Markdown 语法编写文档,界面简洁,生成的文档支持语法高亮和自定义样式。

适用场景:适合需要简单、易维护、可定制静态 API 文档的项目。

8. Postman + Newman

功能:Postman 提供了 API 文档功能,可以从 API 请求集生成文档,而 Newman 是其命令行工具。

特点:Postman 的 API 请求可以直接转化为文档,并支持测试自动化。

适用场景:适合开发和测试过程紧密结合的项目,Postman 的 API 请求集可以作为团队文档使用。

9. OpenAPI Generator

功能:从 OpenAPI 定义生成客户端和服务端代码。

特点:支持多种语言的代码生成,帮助生成规范的客户端或服务端框架。

适用场景:适合希望快速生成多种语言客户端或服务端代码的项目。

评论