DocumentUp

ApiBlueprint is ?

ApiBlueprint is Api’s Blueprint.
ApiBlueprint,是一份新型的“Api文档格式语言”规范。

新规范“Api文档格式语言”的提出,是为了探寻一种简明、规范、轻盈的Api文档结构参考,同时方便扩展成“可执行文档”,比如,调式Api接口,临时提供Mock Sever接口、一键检测Api速度等。

相比之下,对于“Api文档格式语言”的新规范上,有着共同心愿的。
还有mulesoft维护在raml.org API-NoteBook。RAML是“RESTful API Modeling Language”的缩写。
另外的,ApiBlueprint则是Api’s Blueprint的意思,由Apiary.io维护在ApiBlueprint.org。

ApiBlueprint和RAML的提出。一如既往地体现了开放软件工程的魅力。
当工程发展面临沉闷的问题时,开放工程总能有创见性地提出一个有着精致理论的应对方案。

它们都指明了下一代API的规范文档方向。那就是,API in Language。即是,让Api在简明规范中更好地流通使用起来。

为什么选择ApiBlueprint ?

分成两个部分来判断。首先是,ApiBlueprint相比于传统Api手写文档方式(word文档,txt文档),和自动生成web文档方式(Swagger、dexy框架等)都有着版本级别的优越性。具体为,

  1. Api规范更合理&自由。手写的文档受制于项目经理或技术经理的个人经验的“垄断”。
  2. Api文档建立易于上手。不需要像自动生成web文档,需要run几条command,搭配个基本环境。

然后是,ApiBlueprint相比于同类规范,诸如RAML等,优势则是,

  1. 比RAML富有活力。这也是因为RAML屈身于大型软件厂商旗下,RAML的自我纠正和自我更新的速度就远不如Apiary.io这类创业公司手中的ApiBlueprint。
  2. 比RAML精炼。因为程序猿的惯性行为肯定会是逐步最小化使用,所以ApiBlueprint相对来说更精炼直白的表达方式,有助于让API文档长久被维护起来。

ApiBlueprint 格式文档

建议,快速浏览一次文档目录。在以后需要的时候,再回来查阅。

格式文档

来自 ApiBlueprint文档

egs

为什么有ApiBlueprint.cn 和 ApiBox ?

ApiBlueprint和apiary.io做的都很出色。而ApiBoxCN是为了能让ApiBlueprint能够在中国更出色的普及起来。原因有三,

  1. 速度。天朝的墙太高了,使用webApp有不太多不畅快。
  2. 性能。apiary的web编辑板很出色,但是原生应用的迅捷一如既往是工程师的追求。
  3. 隐私。大型项目或者商业机密类API,对于隐私的要求极其苛刻,所以本地存储的apibox很有存在的必要。

简要模板 simpleTemplate

格式文档

标准模板 classicalTemplate

格式文档

参与建议&相关资源

ApiBlueprint支持开源性生长。欢迎一起issue讨论,或者pull request。

www.apiblueprint.org

www.apiary.io

www.raml.org

www.mulesoft.com

www.apibox.cc


本地DNS优化