api⽂档设计⼯具：RAML、Swagger
api⽂档设计⼯具是⽤来描述和辅助API开发的。
⼀、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开发的⼯具，这⾥特别推荐⼀下raml2html与api-console，它们都可以将raml源⽂件转换成精美的doc⽂档页⾯，其中raml2html转换结果是静态的，api-console则可以⽣产可直接交互的api⽂档页⾯，有些类似后⾯要说的Swagger。
raml2html输出的⽂档
api-console⽣成的结果，可以直接在线编辑RAML后解析，也可以给出RAML⽂件远程读取解析
⼆、Swagger
Swagger与RAML相⽐，RAML解决的问题是设计阶段的问题，⽽Swagger则是侧重解决现有API的⽂档问题，它们最⼤的不同是RAML需要单独维护⼀套⽂档，⽽Swagger则是通过⼀套反射机制从代码中⽣成⽂档，并且借助ajax可以直接在⽂档中对API进⾏交互。因为代码与⽂档是捆绑的所以在迭代代码的时候，就能⽅便的将⽂档也更新了。不会出现随着项⽬推移代码与⽂档不匹配的问题。另外Swagger是基于JSON进⾏⽂档定义的。api设计
Swagger⽣成的⽂档
三、API Blueprint
API Blueprint是使⽤Markdown来定义API的，Markdown相⽐前⾯两个RAML、JSON门槛⼜降低了⼀⼤截。同时API Blueprint与前⾯的Swagger、RAML⼀样也能提供可视化的⽂档界⾯与Mock Server的功能。不过其Mock能⼒⽐较弱。
⼯具就是这样的，具体到使⽤还得看你的应⽤场景，对于个⼈开发，⼩项⽬我⽐较喜欢Swagger，代码与⽂档⼀同维护省太多事⼉了，但对于团队开发，使⽤RAML这种建模语⾔进⾏设计与沟通是不错的选择，并且RAML的Mock和⽂档能⼒也不弱，⿇烦就在于增加维护成本，不过既然都团队了这个也就不是什么问题了。⾄于API Blueprint说实话没怎么⽤过，不过感觉⽤Markdown挺美好的。
参考引⽤

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。