学习笔记《Swagger》

在 web 领域面向 API 的开发过程中，接口的格式已经被 JSON 统一差不多了，围绕这一接口格式而延展开来的需求，比如：注释、文档生成、参数设计、协议类型、请求类型、HEAD信息等等一系列的周边，便产生了接口制定标准的需求，目前最主要的解决方案有

1. Swagger
2. API Blueprint
3. RAML

其中 API Blueprint 是我准备用的 apiary.io 深度参与的标准，但是最终我还是选择了 Swagger，（apiary.io 非常开放的同样支持了 Swagger 的标准），原因是 Swagger 具有较为活跃的社区和更开放的沟通渠道，Swagger 和 RAML 都不约而同得选择了 YAML 作为自己的配置文件，可以用 examples 参数在中间插入 mock 的数据，是有其道理的，API Blueprint 在看似简单易用的背后，复用性低的问题在 YAML 前面就显露无疑了

Swagger 对自己的介绍是：The World's Most Popular Framework for APIs. 没错，他把自己当成一个框架

官方提供了一个强大的在线编辑器（不仅仅是编辑）：
http://editor.swagger.io/
在编辑器里面看到的代码大致是这个样子：

info: version: 0.0.0 title: title description: description termsOfService: terms contact: name: Joe url: 'http://example.com' email: [email protected] license: name: MIT url: 'http://opensource.org/licenses/MIT' swagger: '2.0' host: example.com basePath: / produces: \\- application/json paths: /products: get: responses: '200': description: 200 response schema: type: object properties: foo: type: string examples: application/json: |- { "foo": "200 example" } '400': description: 400 response schema: type: object properties: foo: type: string examples: application/json: |- { "foo": "400 example" } '500': description: 500 response schema: type: object properties: foo: type: string examples: application/json: |- { "foo": "500 example" }

Swagger 的不同版本之间并不是兼容的，主要版本是2014年9月稳定下来的2.0版本，这会加重网上搜索解决方案的时候的干扰，好在官方有一份详细的说明文档：
http://swagger.io/specification/

参数类型

支持五种不同的参数

尝试在 apiary.io 使用 Swagger 设计小丑鱼的项目接口，各种悲催，post 提交的时候 array 参数不支持，在 Swagger Editor 中显示正确的格式，在 apiary.io 中显示错误：

Rendering of attributes has failed
This might be related to an invalid MSON definition. If the problem persists, please get in touch with us, we'll take a look.

所以把 apiary.io 和 Swagger 结合在一起使用是行不通的

使用一个 Swagger 支持较好的服务：
https://swaggerhub.com/