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开发的工具,这里特别推荐一下raml2html
与api-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
api文档设计工具:RAML、Swagger的更多相关文章
- REST api文档管理工具
问题: 不同软件/程序在网络中互相传递信息不统一. 交互不便. REST API 作用: RESTful API就是一套协议,用来规范多种形式的前端和同一个后台的交互方式. 原理: 组成/流程/规范: ...
- API文档管理工具-数据库表结构思考.
API文档管理工具-数据库表结构思考. PS: 管理工具只是为了方便自己记录API的一些基本信息,方便不同的开发人员 (App Developer, Restful API Developer)之间的 ...
- Java 的 Api 文档生成工具 JApiDocs 程序文档工具
JApiDocs 详细介绍 简介 JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具.最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs ...
- GhostDoc:生成.NET API文档的工具 (帮忙文档)
在 Sandcastle:生成.NET API文档的工具 (帮忙文档) 后提供另一个生成API文档的工具. 1) 准备工作 安装GhostDoc Proc. 收费的哦.... 这个工具的优势是不像 ...
- API文档管理工具
系统庞大之后,前后端分离开发,前端调用后端提供的接口,请求协议一般是 HTTP,数据格式一般是 JSON.后台只负责数据的提供和计算,而完全不处理展现逻辑和样式:前端则负责拿到数据,组织数据并展现的工 ...
- 【转载】Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景 没有背景.就自己做自己 ...
- [aspnetcore.apidoc]一款很不错的api文档生成工具
AspNetCore.ApiDoc 简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api ...
- Api文档生成工具与Api文档的传播(pdf)
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
- API文档自动生成,Swagger的配置
ASP.NET的部署方式 第一步:引用程序集 打开NuGet程序包管理器,搜索Swagger,安装第一个,注意画圈的地方, 已经包含主程序和UI了,安装完成后会在根目录App_Start文件夹下生成S ...
随机推荐
- nginx目录学习
目录 一. Nginx 基础知识 二. Nginx 安装及调试 三. Nginx Rewrite 四. Nginx Redirect 五. Nginx 目录自动加斜线: 六. Nginx Locati ...
- linux下使用Vsftpd服务传输文件
FTP协议占用两个端口号: 21端口:命令控制,用于接收客户端执行的FTP命令. 20端口:数据传输,用于上传,下载文件数据. 过程: 首先安装vsftpd服务程序使用命令 yum install v ...
- 抽象类 and 接口
目录 抽象类 抽象类的域和方法的权限: 接口 接口中的域和方法的权限: 实现多个接口 接口继承 接口嵌套 抽象类 一个类,如果有抽象方法(没有方法体),则该类必须被限定为抽象类(abstract):当 ...
- LeetCode. 阶乘后的零
题目要求: 给定一个整数 n,返回 n! 结果尾数中零的数量. 示例: 输入: 3 输出: 0 解释: 3! = 6, 尾数中没有零. 解法: class Solution { public: int ...
- WUSTOJ 1274: 喂,这里是帅帅的LCM(Java)
1274: 喂,这里是帅帅的LCM 题目 在一组数中,找出个数为奇数的数.更多内容点击标题. 分析 其实这种题并不难,做过一次之后,绝对不会错第二次.通过读题可以发现,我们要找的那个数在这一堆 ...
- docker 实践四:仓库管理
本篇我们来了解 docker 仓库的内容. 注:环境为 CentOS7,docker 19.03 仓库(Responsitory)是集中存放镜像的地方,又分公共仓库和私有仓库. 注:有时候容易把仓库与 ...
- 冒泡(bubblesort)、选择排序、插入排序、快速排序
冒泡排序(bubblesort) 特点:通过换位置的方式,一直向上冒泡 package main import "fmt" func bubbleSortAsc(arrayA [] ...
- php实现命令行里输出带颜色文字
今天执行composer的时候看到命令窗口出现的提示里面有的关键性部分带有颜色,于是很好奇研究了一下,在这里记录下来 其实在命令行输出带颜色字体主要是使用的 ANSI 转义字符实现的,我们先看个例子: ...
- React实现顶部固定滑动式导航栏(导航条下拉一定像素时显示原导航栏样式)
摘要 基于react的框架开发一个顶部固定滑动式的酷炫导航栏,当导航栏置顶时,导航栏沉浸在背景图片里:当鼠标滑动滚轮时,导航栏固定滑动并展示下拉样式. JS部分 相关技术栈:react.antd.re ...
- vs-code 的常用插件
最近编辑器转移至VS-Code上面了,为什么抛弃sublime呢,因为,sublime在项目逐渐变大的过程中(项目已上万行,还在不停继续变大),sublime会出现卡顿,反应缓慢,甚至未响应状态,基于 ...