api文档设计工具：RAML、Swagger

api文档设计工具是用来描述和辅助API开发的。

1、RAML

https://raml.org/　　https://wenku.baidu.com/view/9523238d5ef7ba0d4b733b16.html###

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开发的工具，这里特别推荐一下raml2html与api-console，它们均可以将raml源文件转换成精美的doc文档页面，其中raml2html转换结果是静态的，api-console则能够生产可直接交互的api文档页面，有些相似后面要说的Swagger。

raml2html输出的文档

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

 

 

2、Swagger

https://mp.weixin.qq.com/s?__biz=MzAwNDYwNzU2MQ==&mid=400011200&idx=1&sn=51f132551bcd5a7d2aabb56047ba6f07&scene=21##

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

Swagger生成的文档

 

 

3、API Blueprint

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

 

工具就是这样的，具体到使用还得看你的应用场景，对于我的开发，小项目我比较喜欢Swagger，代码与文档一同维护省太多事儿了，但对于团队开发，使用RAML这种建模语言进行设计与沟通是不错的选择，而且RAML的Mock和文档能力也不弱，麻烦就在于增长维护成本，不过既然都团队了这个也就不是什么问题了。至于API Blueprint说实话没怎么用过，不过感受用Markdown挺美好的。

参考引用

• https://www.cnblogs.com/softidea/p/5728952.html