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 定义生成客户端和服务端代码。
特点:支持多种语言的代码生成,帮助生成规范的客户端或服务端框架。
适用场景:适合希望快速生成多种语言客户端或服务端代码的项目。