使用 API Blueprint 来编写 API 接口文档
- API Blueprint 是什么
- API Blueprint 语法高亮工具
- API Blueprint 渲染工具
API Blueprint 是什么
API Blueprint 用来编写API文档的一种标记语言,类似于Markdown,具体的语法规则可以在 API Blueprint documentation 查看,文档里面还有一个简短的 API Blueprint tutorial 建议先仔细阅读一下这个教程。
使用 API Blueprint 文档,配合一些开源的工具可以把接口文档渲染成 html 再搭配一个静态服务器,就可以很方便的共享给同事。
相对于 word 这种富文本格式的文档来说,API Blueprint 是纯文本,这样可以很方便的使用版本控制工具 Git 来控制版本。
另外,配合一些工具,可以直接生成一个 mock data 数据,这样只要和后端的同学约定好接口格式,那么前端再开发的时候可以使用 mock data 数据来做测试,等到后端写好接口之后再做联调就可以了。
API Blueprint 语法高亮工具
API Blueprint 社区提供了一些文本编辑器的插件,可以识别 API Blueprint 语法支持语法高亮。
API Blueprint 渲染工具
使用 apiblueprint 编写好文档使用,可以使用开源社区提供的一个工具 aglio 来把接口文档渲染成 html 文件,aglio 还会启动一个静态服务器,这样就可以在浏览器里面查看渲染好的文档了。
aglio 的使用教程,可以直接查看官方开发仓库的 readme 文档。另外,这里也有一份资料 使用API-Blueprint 编写 API 文档可以参考。