快速了解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-ui
Swagger-ui 是一套 HTML/CSS/JS 框架，用于渲染 Swagger 文档，以便提供美观的 API 文档界面。

也就是说，Swagger-ui 是一个 UI 渲染工具。

 

 

swagger的生态使用图：

 

 

 

 

swagger-validator

这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单，只需url地址栏，根路径下加上一个参数url，参数内容是放swagger说明文件的地址。即可校验。 

比如：

 

 

swagger-codegen
代码生成器，脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。 
有一定用处，Java系用的挺多。工业上应该不咋用。

 

mock server
这个目前还没有找到很合适的mock工具，包括rap也好，其他API文档工具也好，都做的不够完善，大多就是根据说明文件，例如swagger.json等生成一些死的静态的mock数据，不能够根据限定条件：例如“只能是数字，必传”等做出合理的回应。
 

 

 

 

参考资料：

https://blog.csdn.net/i6448038/article/details/77622977#commentBox

https://blog.csdn.net/lamp_yang_3533/article/details/80114083