通过 Swagger 建模工具编写 RESTful API 接口之前，应该先了解的相关知识。
RESTful
既然是写 RESTful API 接口，那么 RESTful 相关的知识应该要很熟。
JSON
服务器与客户端通过 API 进行交互时，数据传输的文本类型使用 XML 还是 JSON ？
通过这张 比较 XML 和 JSON API Google 的趋势图，你应该使用基于 JSON 的媒体类型（Content-Type: application/json）作为数据交换格式。
YAML
你可以通过 JSON 或者 YAML 在 Swagger 上编辑 API 接口文档。
YAML 的优势：专门用于编写配置文件，支持添加注释，而且语法更简洁，更利于书写和阅读。
当然，Swagger 也提供 YAML 和 JSON 相互转换的工具。
通用标语（commonMark）- 就是 markdown
如果你想要在 YAML 文档中编辑添加富文本（比如文本加粗），就需要了解 markdown 相关的语法知识。
OpenAPI
OpenAPI：一套通过 Swagger 编写 RESTful API 文档的语法标准。
💡 推荐采用最新的 OpenAPI 3.0 规范。
2016 年 1 月，Swagger 将 Spec（Swagger API Spec）捐献给 Open API Initiative (OAI)，成为 Open API Spec 的基础。
OpenAPI 基于 Swagger 2.0 构建，Swagger 是 SmartBear 贡献给 Linux 基金会的。意在构建具有中立管理模型的新组织，以引领 Swagger 更上一层楼。“开放 API 战略” 的创始成员包括对贡献具有兴趣的 Google、IBM 和 Microsoft。同时还成立了一个技术开发者社区（TDC，Technical Developer Community）以对规范做开发。TDC 对于任何有意向做出贡献的个人都是开放的，无需会员身份。
- OpenAPI 3.0 中文手册
- OpenAPI Specification
- OpenAPI 规范 3.0 版接近最终发布
- OpenAPI Map - 通过动态导图的方式呈现 OpenAPI 规范
swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。
当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。
工具
- Swagger 官网
- Swagger API Spec，描述 Rest API 的语言，标准就是上面所说的 OpenAPI；
- swagger editor，Swagger API Spec 的编辑器
- swagger ui，将 Swagger API Spec 以 HTML 页面展现出来的模块 | github
- swagger2markup
