OpenAPI与YAML

1. Swagger

The World’s Most Popular Framework for APIs.
OpenAPI v2.0规范（也就是SwaggerV2.0规范）

2. OpenAPI

OpenAPI规范是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。OpenAPI规范帮助我们描述一个API的基本信息，比如：

1. 有关该API的一般性描述
2. 可用路径（/资源）
3. 在每个路径上的可用操作（获取/提交…）
4. 每个操作的输入/输出格式

3. 使用OpenAPI规范

OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出
根据OpenAPI规范编写的二进制文本文件，能够像代码一样用任何VCS工具管理起来
一旦编写完成，API文档可以作为：
需求和系统特性描述的根据
前后台查询、讨论、自测的基础
部分或者全部代码自动生成的根据
其他重要的作用，比如开放平台开发者的手册…

4. YAML

YAML 语言（发音 /ˈjæməl/ ）的设计目标，就是方便人类读写。它实质上是一种通用的数据串行化格式。

它的基本语法规则如下。

大小写敏感
使用缩进表示层级关系 缩进时不允许使用Tab键，只允许使用空格。
缩进的空格数目不重要，只要相同层级的元素左侧对齐即可

’ #’ 表示注释，从这个字符一直到行尾，都会被解析器忽略。

YAML 支持的数据结构有三种。

1. 对象：键值对的集合，又称为映射（mapping）/ 哈希（hashes） / 字典（dictionary）
2. 数组：一组按次序排列的值，又称为序列（sequence） / 列表（list）
3. 纯量（scalars）：单个的、不可再分的值

5. API开发规约

• 接口维护者使用swagger2提供的swagger editor，依据OpenAPI规范手动编写swagger.yaml接口定义文档。
• 生成在线的 HTML 格式的 API文档托管到网站上面，前端和后端工程师可在线查看api文档。
• 如果有需要也生成一份PDF格式的文档，以便随时可以分发出去。
• 如果开发过程中接口变更，接口维护者重新编写接口定义文档，然后重新生成新的API文档，并通知前端和后端工程师更新内容。

其他详细信息参考一下链接：

参考链接： Swagger从入门到精通
swagger在线编辑器：在线编辑器