API Blueprint

对 API 文档的幻想

你对 API 文档有哪些需求？写起来方便看起来舒服？

这两个应该是文档最基本的需求了。

其实，先后端配合开发的时候，还经常会有这样一种需求：

“你接口定义好了吗？定义好了的话能不能先帮我作一个 Mock Server 让我先跑起来？”

  

apiary

曾经和前端同事合做开发的时候，就意外发现了这样一个网站。

在上面能够用 Markdown 的语法写文档，只要用统一的格式边写，它就能自动生成漂亮的展现页面和 Mock Server。

网站作的很是好，免费版能够供小团队使用。

最近发现，这家公司把它们的这套 API 标准开源了，还有对应的 Parser，Renderer，Mock Server，Editor等等。配套设施很是全，彻底能够本身搭一个了。

相关标准和工具在这里：https://apiblueprint.org/

  

编辑器

编辑器其实很是简单，由于是基于 Markdown 的，因此若是你的编辑器支持 Markdown 语法高亮就好了，总之就是你爱用什么就用什么。

可是社区也有人作了一些插件，例如 api-blueprint-preview 就能够更方便地预览最终效果，还有这个插件 linter-api-blueprint 能够检查语法错误。

Atom 下插件最多，总之编辑器彻底不是个问题。

API Blueprint 有本身的后缀名：apib，并且 github 能够识别它！

  

Renderer

Renderer 是什么呢？它主要负责把你用 Markdown 写的文档渲染成静态 HTML 页面。

这里介绍一下：aglio

安装起来很是简单：

npm install -g aglio

用起来也一样简单：

aglio -i document.apib --theme-template triple -o output.html

最终效果：

它能够多种模板，也能够自定义样式，更多需求能够看它的文档。

  

Mock Server

Mock Server 就要靠另外一个工具了：drakov

安装起来一样很简单：

npm install -g drakov

而后跑起来：

drakov -f "*.md"

你会看到以下信息：

而后直接去浏览器中访问便可。

 

自动化

相关工具都搞定了，还缺什么呢？主要就差自动化部署了，每次人肉重启是不可能的。

但这块没有现成的工具，或者说这块能够和现有的不少工具配合，例如配合 Jenkins 再写点脚本，很快就能实现了。

 

源地址:http://www.dozer.cc/2016/01/api-blueprin...