如何写好swagger文档

什么是swagger

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。 浏览 Swagger-Spec 去了解更多关于Swagger 项目的信息，包括附加的支持其他语言的库。
http://swagger.io

编写方式

1. 学习swagger-specification，通过swagger-editor手动编写
2. 通过注释编译生成，如swagger-php
   主要介绍每一种

相关工具

swagger
    OAS(openapi specification)
    swagger-editor
    swagger-ui
    swagger-php
postman
mockjs
    [sosoapi](http://www.sosoapi.com)
    [easy-mock](https://www.easy-mock.com)

http://chancejs.com
https://github.com/dzdrazil/swagger-mock-api
https://github.com/mrVanDalo/swagger-api-mock-docker

学习资料

https://huangwenchao.gitbooks.io/swagger/content/
http://editor2.swagger.io/

参考例子

http://petstore.swagger.io/
http://petstore.swagger.io/v2/swagger.json

工作流

1. 后端根据需求通过swagger-editor写api文档，规定接口输入输出，并生成swagger.json，可以导入swagger-ui交付给前端
2. 前端根据后后端提供的swagger.json导入postman做开发测试，或通过接口文档开发测试，同时可以利用sosoapi或easy-mock辅助生成mock接口，先对接。

多人协作可以遇到的问题

1. 同一套文档经常修改，冲突不好解决
2. 后端更新文档，前端不知道
3. 文档更新自动生成

参考资料
https://swagger.io/specification/
http://www.jianshu.com/p/6840514c4c8e
https://huangwenchao.gitbooks.io/swagger/content/