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

[skyrem]

#写在前面

首先我所在的是小公司小项目，我也研究过 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 格式的文档，大功告成！

[undeflife]

在 api 的实际开发前先写 api 设计文档和示例代码其实是从需要设计者站着使用者角度整体的思考 api 各个细节，跳过这一步直接开发很自然的以开发的便利性为主和可能忽略掉使用者的需求，这样没有涉及的 api 使用工具产生出再详细的文档一样没法避免使用 api 的人骂垃圾，开发 api 的骂使用者 sb 的情况

[skyrem]

@undeflife #1 这样前后端互相责怪的情况确实是我的这个流程中无法避免的

[xsir2020]

而且没有设计的话，很容易变成 rpc 形式的 api , 如 getuserinfo
稍微有设计的话，可能更容易变成偏 restful 风格一些

[makdon]

谢谢分享。postman 的自带的文档只能在线看不方便归档，找了各种方法没解决，当时听说过 blueprint，想不到还有
postman 转 blueprint 的工具。

[prasanta]

现在有一个不用文档的解决方案，前端使用 json 描述一个组件，json 对应一个表单验证。组件 json 与校验 json 都是从后端返回，前端对字段类型无感知。

[shuizhengqi]

swagger 不是挺好？

[skyrem]

@shuizhengqi #6 前面已经说过了，swagger 和 apiary 差不多，只是我没有设计 api 的阶段

不过 1，3 楼两位老哥的回复让我重新审视了设计 api 的重要性，只是目前我所在的环境无法推行这样完整的工作流

[skyrem]

@prasanta #5 你是指 apijson 吗

[prasanta]

前后端用同一 jsonschema

[balabalaguguji]

强烈推荐你试下易文档，接口文档、接口测试、Mock 整合在一起的，可以生成非常漂亮的文档
https://easydoc.top