今年标志着OpenAPI 3.0的正式发布,这是OpenAPI规范的最新版本。
对于从事API开发的人来说,OAS 3.0的发布,嗯……意义重大。
为什么?其中一个最值得注意的原因是,OpenAPI 3.0是该规范自2015年由SmartBear Software捐赠给OpenAPI Initiative并从Swagger Specification更名为OpenAPI specification以来的首次正式发布。
在我们深入探讨OpenAPI 3.0对API领域为何如此重要的原因之前,首先澄清一些关于OpenAPI的问题以及它对Swagger意味着什么,这一点很重要。
在过去两年中,关于从Swagger到OpenAPI的更名存在很多疑问。同时,关于OpenAPI和Swagger之间的区别、何时使用哪个名称以及OpenAPI和Swagger之间的关系也存在很多困惑。
让我们从澄清Swagger与OpenAPI的区别开始
理解两者区别的最简单方法是
- OpenAPI = 规范
- Swagger = 实现该规范的工具
OpenAPI是该规范的官方名称。该规范的开发由OpenAPI Initiative推动,该组织汇集了来自技术领域不同地区的30多家组织——包括Microsoft、Google、IBM和CapitalOne。Smartbear Software作为主导Swagger工具开发的公司,也是OpenAPI Initiative的成员,帮助引领规范的发展。
Swagger与一些最知名、最广泛使用的实现OpenAPI规范的工具相关联。Swagger工具集包括开源、免费和商业工具的组合,可在API生命周期的不同阶段使用。
这些工具包括
由于Swagger工具是由参与创建原始Swagger Specification的团队开发的,因此这些工具通常仍被视为该规范的代名词。但是Swagger工具并不是实现OpenAPI Specification的唯一可用工具。有各种各样的API设计、文档、测试、管理和监控解决方案支持2.0版规范,并正在积极致力于增加3.0版支持。
您可以在GitHub上找到支持最新版OpenAPI规范的完整工具列表。
为什么Swagger工具没有改名为OpenAPI?
Swagger生态系统始终由规范及其核心开源工具组成,其中最著名的是Swagger UI、Swagger Editor和Swagger Codegen。规范之所以被广泛采用,一个重要原因是与其并存的工具。
SmartBear捐赠了该规范,但流行的开源Swagger工具仍然保留了原始品牌,因为开发人员、技术文档工程师、测试人员和设计师对这些工具有着强烈的认同。该规范不是,也从未仅仅与Swagger工具相关联。事实上,捐赠该规范并成立OpenAPI Initiative的决定是为了确保OpenAPI完全保持供应商中立。这就是为什么我们很高兴看到API领域的如此多公司,包括那些也支持其他定义格式(如API Blueprint和RAML)的公司,加入了该倡议。
Swagger团队仍然专注于构建最强大、易用的工具,用于使用OpenAPI Specification设计、文档化、开发和测试API,并将继续发展和完善我们的工具集以支持OpenAPI。这些工具将继续保留Swagger名称。Swagger.io,作为Swagger工具和开源Swagger项目的在线主页,也将继续是了解Swagger工具的首选之地,我们也将通过培训、教程、网络研讨会和文档等方式,继续为OpenAPI Specification相关知识做出贡献。
了解OpenAPI和Swagger社区
虽然为OpenAPI做出贡献的人员与为Swagger工具做出贡献的人员之间总会有重叠,但这两个社区是相互独立的。
如本文所述,OpenAPI Initiative是一个开放的、供应商中立的组织,欢迎任何希望在API开发中帮助演进或利用该规范的人参与。我们邀请各组织加入不断壮大的规范贡献者名单,也欢迎个人通过在GitHub上分享想法和反馈,或参加每月在全球各地举办的众多OAS聚会来参与。点击此处了解更多如何贡献。
Swagger工具拥有自己的社区,专注于帮助改进现有的Swagger项目,并引入新的想法和功能请求。Swagger社区由SmartBear Software团队培育,该团队投资于开源Swagger工具的开发,但也受到全球数千名Swagger用户的贡献驱动。如果您想加入Swagger社区,我们邀请您在GitHub上找到我们或加入Swagger API Meetup群组。您还可以在Swagger博客或Twitter上的@SwaggerAPI上找到最新消息和更新。
展望OpenAPI的光明未来
我们期待看到OpenAPI成为API领域人人皆知的名称,并很高兴能成为OpenAPI Initiative不断壮大的社区成员之一。
希望本文能帮助澄清一些关于OpenAPI及其与Swagger关系的问题。
总结
- 该规范于2015年更名为OpenAPI Specification。OpenAPI 3.0是该规范的最新版本。
- 由SmartBear Software支持的Swagger工具是实现OpenAPI Specification最受欢迎的工具之一,并将继续保留Swagger名称(Swagger Editor、Swagger UI、SwaggerHub等)。
- 还有数百种与Swagger无关的开源和专业工具支持OpenAPI 2.0 Specification,支持3.0的工具列表正在持续增长。
- OpenAPI和Swagger都拥有开源社区,欢迎所有贡献者加入,分享他们的想法并参与其中。
如果您有同事、朋友或任何其他从事API工作的人仍然存在这些疑问,我们希望您能分享这篇文章。Swagger团队将努力帮助澄清Swagger和OpenAPI之间的关系,我们也希望您能这样做!
Swagger入门:OAS与Swagger工具介绍
请在11月14日加入我们的免费培训,该培训将介绍Swagger工具生态系统和OpenAPI规范。了解更多。