Swagger 入门 [II] - 但为什么要用它?

  2015 年 10 月 15 日

作者: Ron Ratovsky

在该系列的上一篇文章中,我们介绍了 Swagger 的基本概念及其外观。这次我们将讨论使用 Swagger 的一些好处。

通用语言 - 作为一种规范,Swagger 拥有一套易于遵循和理解的规则。 使用它可以帮助 API 生产者和消费者之间建立共同的基础。 具有(开发)语言无关性意味着应用程序之间更容易互操作。

人机友好 - Swagger 支持 JSON 和 YAML 两种格式,最终可以方便人类和机器的阅读和编写。 对于用户来说,YAML 是一种更容易使用的格式,因为它比 JSON 更简洁。 用户还可以选择使用多种可视化工具之一来查看文档的呈现版本并与之交互。 对于机器来说,可以使用各种库来解析这两种格式,从而实现强大的集成。

API 生命周期 - 无论您是希望将 API 的手动维护文档替换给用户,还是希望控制应用程序的整个 API 生命周期,Swagger 都能满足您的需求。 设计、文档、代码生成、测试、API 管理、监控 - 选择一个,选择多个,由您选择。

开发过程集成 - 您可能有一个现有的 API,或者您可能希望创建一个新的 API,但无论哪种方式,Swagger 都能满足您的需求。 使用众多语言集成之一,直接从您的代码中生成 Swagger 文档,或使用 Swagger Editor 来计划和设计您的 API,将其用作您的事实来源。 如果您愿意,您甚至可以从现有的 API 转移到合同优先的方法。 最近,我们引入了一种新方法,允许您保持 Swagger 定义和代码松散耦合,但仍然连接在一起。 这由 swagger-node(适用于 node.js)或 swagger-inflector(适用于 Java)提供。

社区驱动 - 自 Swagger 首次公开以来,它就受到用户请求的影响。 Swagger 2.0 由一个由 400 人组成的开放小组推动,这些人来自大型公司、小型初创公司,甚至一些自我代表的用户。 每个人都可以表达自己的意见,提出他们的痛点并推动规范向前发展。 我们现在有一个专门的 github 存储库,我们的用户可以在其中打开功能请求、评论现有请求,并总体上影响 Swagger 的未来。

不断增长的工具集 - 有无数工具支持 Swagger,包括 开源商业。 各种工具旨在促进语言集成,并将 Swagger 插入到 API 生命周期的不同部分。 越来越多的工具会定期添加,涵盖更多的框架和生命周期中的新方面。

在下一部分中,我们将介绍一些使您的第一个 Swagger 定义准备就绪以供使用的方法。