看到一个小型、特立独行的开源项目改变了整个行业的看法,这相当引人入胜。Swagger 规范就是这样,这个开源 API 设计标准发展出了一个完整的开发者社区,围绕它建立了一个强大的工具生态系统,并最终演变为OpenAPI 规范 (OAS)——定义 RESTful 服务的世界标准。作为 Swagger 规范初始版本背后的公司和团队,能参与这项创新是我们的荣幸。今天,我们很高兴地宣布 SwaggerHub 将支持下一版 OpenAPI 规范 3.0。
为什么选择 OpenAPI 规范 3.0
OAS 3.0 为您的 API 设计带来了各种丰富、富有表现力的功能。其结构已重构以变得更加简单。例如,参数、响应、示例等可重用对象都被归入 `components` 对象下,而令人困惑的 `body` 参数已被 `requestBody` 取代,`formData` 也归于其下。此外,还有一系列新功能,如链接、回调、多个服务器主机和更好的安全定义。您可以在我们即将举行的培训中了解所有新变化:
OpenAPI 3.0:如何使用最新 OpenAPI 规范设计和文档化 API。 OAS 3.0 功能丰富的描述集允许架构师、开发人员和技术文档编写者在没有限制的情况下更好地描述他们的 API,并提升了消费体验。行业正在推进 OAS 3.0 的采用,并且围绕该规范构建了新的工具。上个月,我们在
Swagger Editor 和 UI 以及
Swagger Core 中提供了对 OAS 3.0 的支持,现在这一支持已扩展到 SwaggerHub,因此您的团队可以使用 OAS 3.0 协作进行 API 设计和文档化过程。
SwaggerHub 能提供什么?
设计与文档
SwaggerHub 编辑器支持 OAS 3.0 来设计和文档化 REST API。这意味着您在设计 API 时可以利用编辑器的自动完成、错误反馈和语法验证功能,同时可视化您的 OAS API。SwaggerHub 还会自动生成并托管您通过 OAS 定义的 API 文档,因此您拥有一个平台来满足所有 API 设计和文档需求。创建新 API 时,您可以指定要使用的规范版本,从而灵活地根据您的需求定义 API。如果您选择导入定义,SwaggerHub 还可以自动确定规范类型。通过 OAS3.0 徽章,您可以轻松识别您的 API 是否在 SwaggerHub 上以最新 OAS 定义。

Swagger 到 OAS 3.0 的转换
每当框架引入新版本时,最大的挑战之一就是迁移。SwaggerHub 支持将现有的 Swagger 2.0 规范转换为最新的 OAS 3.0。这种即时转换将在 API 中创建一个带有
-oas3 后缀的新版本。您原始的 API 版本将保持不变。

这意味着您不再需要花费数小时尝试破译和更改 API 定义中的每一行,或者通过插件艰难地升级您的 API 到最新版本,只需点击转换,即可看到您的定义转换为 OAS 3.0。
太棒了!为什么 OAS 3.0 支持仍然处于测试阶段?
尽管我们在使用 OAS 3.0 设计、文档化、转换和协作 API 方面提供了强大的支持,但我们仍在努力提供更多功能以全面支持 OAS 3.0。这包括——
- 使基于 OAS 3.0 的 API 文档具有交互性
- 为基于 OAS 3.0 的 API 启用模拟功能
- 从 OAS 3.0 API 生成服务器代码和客户端 SDK
- 为 SwaggerHub 域添加 OAS 3.0 支持
尽管如此,我们正在积极努力,尽快添加上述功能。我们始终感谢用户提出的任何反馈或功能请求,因此请随时通过电子邮件直接联系我们:
[email protected],提供您对 OAS 3.0 支持的意见。
您可以从我们的帮助文档中了解更多关于使用 OAS 3.0 的信息。 开始使用 OpenAPI 3.0
您可以在 SwaggerHub 中开始使用
OpenAPI 3.0 设计和文档化新旧 API。SwaggerHub 编辑器允许您使用 OpenAPI 3.0 定义和可视化您的 API,或将使用 Swagger 2.0 定义的现有 API 转换为最新版本的规范。
立即开始。