后端 API 开发流程分享-自动生成文档

#写在前面

首先我所在的是小公司小项目，我也研究过 apiary 的开发流程，跟我现在的实际流程不符，没有设计 api 的阶段，自然没有 api-mock，所以才有了我现在的开发流程：

明确需求->编写 api->测试->自动生成文档

#需要的工具

postman

postman to blueprint pmtoapib

aglio

requester (optional)

#开发流程

明确了需求以后，就开始编写 api 供前端调用 因为需要测试，我觉得apijson应该也挺适合这个开发流程的，只是目前暂时没有使用过。

api 写好之后就使用 postman 测试接口是否工作正常,这里我用的是 sublime 的 requester 插件做测试，postman 有一个capture的功能，大概意思就是你在使用 requester 测试接口的时候配置一个 proxy 地址，像这样

###env
8min = 'http://8min.somesite.com/api/'

# postman capture
proxies = {
  "http": "http://127.0.0.1:5555",
  "https": "http://127.0.0.1:5555",
}
###env


## group 1
# get('httpbin.org/get', params={'key1': 'value1', 'key2': 'value2'})

post(8min + 'userinfo/getUserInfo', json={'user_id': 1}, proxies=proxies)

,开着 postman，你的请求就会被记录下来。 到这里其实可以用 postman 的团队分享功能推给前端，然后前端就可以根据 postman 里的数据去请求接口了

这个流程其实 apizza 也可以做，apizza 我用了一段时间总觉得不太好用，可能我还是希望能像我现在这个流程一样，能在编辑器中把开发和测试的工作都做了，自动生成个文档比较好

测试通过之后把 postman 里的数据导出成 json 文件，然后用上面提到的 pmtoapib 转成 blueprint 格式，注意 postman 导出的时候要选 collection v2 格式，v2.1 这个 pmtoapib 的工具貌似还不支持，也可以转文档，但是文档里不带 api 接口请求到的数据样例

最后，使用 aglio 把转换的 apib 文件生成 html 格式的文档，大功告成！