Swagger 入门和实战

简介

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。

Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的，和编程语言无关的 API 描述规范。

应用场景

• 如果你的 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）。

规范

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/ 。

Swagger 文档

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

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

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

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

Swagger 文档（swagger.json 或 swagger.yaml）中关于 API 的描述必须符合 Swagger 规范，Swagger 文档是整个 Swagger 生态的核心。

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

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

工具

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

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

Swagger-editor

Swagger-editor 主要用于编写符合 Swagger 规范的 RESTful API 文档，即编写 Swagger 文档。

Swagger-editor 是一个编辑器，可编写 Swagger 文档，来准确描述 API 信息。

Swagger-editor 可采用两种语法风格：

• YAML 语法
• JSON 语法

当然，不使用 Swagger-editor 也可以，你可以使用任何编辑器来编写 Swagger 文档。

Swagger-editor 的功能

• 编写 Swagger 文档
• 实时检测 Swagger 文档是否符合 Swagger 规范
• 调试 Swagger 文档里描述的 API 接口
• 转换 Swagger 文档（yaml 转 json，或 json 转 yaml）

可见，Swagger-editor 编辑器比一般的编辑器更适合编写 Swagger 文档。当然 Swagger-editor 的功能还不止上面这些。因此，推荐使用 Swagger-editor。

Swagger-editor 的安装和使用

Swagger-editor 有两种方式使用：