Swagger 是最流行的 API 开发工具,它遵循 OpenAPI Specification(OpenAPI 规范,也简称 OAS)。Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。Swagger 是一种通用的,和编程语言无关的 API 描述规范。

1、Swagger应用场景

  • 如果你的 RESTful API 接口都开发完成了,你可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json 文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户。
  • 如果你的 RESTful API 还未开始,也可以使用 Swagger 生态,来设计和规范你的 API,以 Annotation (注解)的方式给你的源代码添加额外的元数据。这样,Swagger 就可以检测到这些元数据,自动生成对应的 API 描述信息。也就是说,Swagger 支持自动生成 API 文档。

Swagger 生态对 JAVA 的支持非常好,但对 PHP 的支持却略显不足。如果想要在 PHP 中自动生成 API 文档,可尝试使用Swagger-php(目前仅兼容 Swagger 2.0 specification)。

2、Swagger规范

Swagger Specification(Swagger 规范),规定了如何对 API 的信息进行正确描述。

Swagger 规范,以前称作 Swagger Specification,现在称作 OpenAPI Specification(简称 OAS)。

Swagger 规范学起来也不难,想熟练使用 Swagger 就必须熟悉 Swagger 规范。

Swagger 规范本身是与编程语言无关的,它支持两种语法风格:

  • YAML 语法
  • JSON 语法

这两种语法风格可以相互转换,都可以用来对我们的 RESTful API 接口的信息进行准确描述,便于人类和机器阅读。

在 Swagger 中,用于描述 API 信息的文档被称作 Swagger 文档。

Swagger 的规范主要有两种:

  • Swagger 2.0
  • OpenAPI 3.0

OpenAPI 3.0 规范是在 2017 年发布的,它在 Swagger 2.0 的基础上进行了优化,包括废弃某些关键词(host、basePath等),新增了一些关键词(servers、components、securitySchemes 等)。

OpenAPI 3.0 比 Swagger 2.0 更强大,使用起来更加灵活、方便。推荐使用 OpenAPI 3.0 。

关于 Swagger 规范的详细信息,请参考官方文档https://swagger.io/docs/

3、Swagger 文档

Swagger 文档(文件),指的是符合 Swagger 规范的文件,用于对 API 的信息进行完整地描述。

Swagger 文档是整个 Swagger 生态的核心。

Swagger 文档的类型有两种:yaml 文件和 json 文件。

yaml 文件用的是 YAML 语法风格;json 文件用的是 JSON 语法风格。这两种文件都可以用来描述 API 的信息,且可以相互转换。

简单的说,Swagger 文档就是 API 文档,只不过 Swagger 文档是用特定的语法来编写的。Swagger 文档本身看起来并不美观,这时,就需要一个好的 UI 工具将其渲染一番,这个工具就是 Swagger-ui。

我们可以用任何编辑器来编写 Swagger 文档,但为了方便在编辑的同时,检测 Swagger 文档是否符合规范,就有了 Swagger-editor 编辑器。

4、Swagger工具组件

Swagger 生态主要包含以下几种工具:

  • Swagger-editor 是一种编辑器,用于编写 Swagger 文档,还支持文档实时检测、API 调试等功能。
  • Swagger-ui 是一种 UI 渲染工具,用于渲染 Swagger 文档,以提供美观的 API 界面。
  • Swagger-codegen 是一种代码生成器,可基于 Swagger 文档,来构建服务器端 stub 和 客户端 SDK。

推荐文档