Swagger 入门 [二] - 为什么?

  2015年10月15日

作者:Ron Ratovsky

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

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

人机友好 - Swagger 支持 JSON 和 YAML 两种格式,这使得它既易于人类读写,也易于机器处理。对于用户而言,YAML 是一种更容易使用的格式,因为它比 JSON 更简洁。用户还可以选择使用多种可视化工具之一来查看文档的渲染版本并与之交互。对于机器而言,这两种格式都可以通过各种现有库进行解析,从而实现强大的集成。

API 生命周期 - 无论您是想用 Swagger 替换手动维护的 API 文档,还是想完全掌控应用程序的整个 API 生命周期,Swagger 都能满足您的需求。设计、文档、代码生成、测试、API 管理、监控——选择其一,选择多个,由您决定。

开发过程集成 - 无论您是已有 API 还是打算创建新 API,Swagger 都能满足您的需求。您可以使用现有的许多语言集成之一,直接从代码中生成 Swagger 文档;或者使用 Swagger Editor 规划和设计您的 API,并将其用作事实来源。如果您愿意,甚至可以从现有 API 转向契约优先(contract-first)的方法。最近,我们引入了一种新方法,允许您将 Swagger 定义与代码松散耦合但仍保持连接。这可以通过 swagger-node(适用于 Node.js)或 swagger-inflector(适用于 Java)实现。

社区驱动 - 自 Swagger 首次公开以来,它就受到用户请求的影响。Swagger 2.0 由一个由来自大型公司、小型初创企业甚至一些独立用户组成的 400 人开放小组推动。每个人都可以发表意见,提出痛点并推动规范向前发展。我们现在为该规范设立了一个专门的 GitHub 仓库,用户可以在其中提出功能请求、评论现有请求,并普遍影响 Swagger 的未来发展。

不断增长的工具集 - 有无数工具支持 Swagger,包括 开源工具商业工具。这些工具旨在促进语言集成,并将 Swagger 融入 API 生命周期的不同环节。越来越多的工具定期添加,覆盖了更多的框架和生命周期中的新方面。

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

© . All rights reserved.