zoukankan      html  css  js  c++  java
  • api文档设计工具:RAML、Swagger

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

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

    raml2html输出的文档

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

    二、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生成的文档

    三、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

  • 相关阅读:
    CSU 1333 Funny Car Racing
    FZU 2195 检查站点
    FZU 2193 So Hard
    ZOJ 1655 FZU 1125 Transport Goods
    zoj 2750 Idiomatic Phrases Game
    hdu 1874 畅通工程续
    hdu 2489 Minimal Ratio Tree
    hdu 3398 String
    洛谷 P2158 [SDOI2008]仪仗队 解题报告
    POJ 1958 Strange Towers of Hanoi 解题报告
  • 原文地址:https://www.cnblogs.com/heroljy/p/9896698.html
Copyright © 2011-2022 走看看