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

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 2046 天前的主题，其中的信息可能已经有所发展或是发生改变。

#写在前面

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

Postman

API

文档

流程

10 条回复 • 2019-12-24 11:45:03 +08:00

undeflife

2019-05-12 19:39:15 +08:00

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