API设计:Swagger, Blueprint和RAML

Swagger

Swagger与RAML相比,RAML解决的问题是设计阶段的问题,而Swagger则是侧重解决现有API的文档问题,它们最大的不同是RAML需要单独维护一套文档,而Swagger则是通过一套反射机制从代码中生成文档,并且借助ajax可以直接在文档中对API进行交互。因为代码与文档是捆绑的所以在迭代代码的时候,就能方便的将文档也更新了。不会出现随着项目推移代码与文档不匹配的问题。另外Swagger是基于JSON进行文档定义的。

python flask swagger 插件:

https://github.com/rantav/flask-restful-swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。其将维护接口文档的工作,与维护代码相结合,使得二者可以齐头并进,随着代码文件的更新,文档也得到了更新。


RAML

RAML(RESTful API Modeling Language 即 RESTful API 建模语言)是对 RESTful API的一种简单和直接的描述。它是一种让人们易于阅读并且能让机器对特定的文档能解析的语言。RAML 是基于 YAML,能帮助设计 RESTful API 和鼓励对API的发掘和重用,依靠标准和最佳实践从而编写更高质量的API。通过RAML定义,因为机器能够看得懂,所以可以衍生出一些附加的功能服务,像是解析并自动生成对应的客户端调用代码、服务端代码 结构, API说明文档。

上面这段引用自网络,这是我见到的对RAML最清晰的描述了。RAML本质上可以理解为一种文档的书写格式,这种格式是特别针对API的,就像Markdown是针对HTML的一样。并且RAML也同样具备了像Markdown那样的可读性,即使是看RAML源码也能很快明白其意图。另外基于RAML语言,有不少辅助API开发的工具,这里特别推荐一下raml2htmlapi-console,它们都可以将raml源文件转换成精美的doc文档页面,其中raml2html转换结果是静态的,api-console则可以生产可直接交互的api文档页面,有些类似后面要说的Swagger。

raml2html输出的文档


api-console生成的结果,可以直接在线编辑RAML后解析,也可以给出RAML文件远程读取解析




API Blueprint

API Blueprint是使用Markdown来定义API的,Markdown相比前面两个RAML、JSON门槛又降低了一大截。同时API Blueprint与前面的Swagger、RAML一样也能提供可视化的文档界面与Mock Server的功能。不过其Mock能力比较弱。


你可能感兴趣的:(API设计:Swagger, Blueprint和RAML)