摘要:是一套描述标准,和一样,属于一种标记语言,可以把标记文稿转换成漂亮的接口文档。还可以创建,进行本地调试。一语法只要用写过东西基本很快就能掌握语法。参考文档使用编写文档用生成优雅的文档指导手册用生成优雅的文档
前后端配合开发的时候,常常会有这样一种需求:
“你接口定义好了吗?能不能先帮我起一个 Mock Server 先跑起来?”
那么,如何才能避免前后端开发在时间差上的无谓等待呢?api-blueprint,也许就是你想要的福音。
API Blueprint是一套API描述标准,和Markdown一样,属于一种标记语言,可以把标记文稿转换成漂亮的接口文档。还可以创建 mock server ,进行本地调试。
一、语法只要用 markdown 写过东西, 基本很快就能掌握API Blueprint Language 语法。
官方 例子 ,一共也就 10 多个,耐心看完,心里就大概有数了;
语法规范;
官方 解释器 ,有了这个解析器,就可以很容易的扩展自己的相关工具了(比如代码生成等)
二、Mock serverapi-mock
drakov
两者都可以根据 api-blueprint 的文档创建一个本地的 mock server 。
安装与使用都非常简单,只要选其中的一种安装即可,确保本地装有 node 环境:
$ node -v
如果能获取到版本号,如:
v6.5.0
就可以直接安装mock工具啦,如果不行的话自行Google一下安装一个呗。
2.1 工具一:安装api-mock$ npm install -g api-mock
启动 mock server,方法中的 api.md 就是所需 server 的 api-blueprint 文档名
& api-mock ./api.md --port 30002.2 工具二:安装drakov
$ npm install -g drakov
启动 mock server,方法中的 api.md 就是所需 server 的 api-blueprint 文档名
$ drakov -f api.md -p 3000三、生成静态 HTML
aglio 是一个可以根据 api-blueprint 文档生成静态 HTML 页面的工具。
aglio不是简单的 markdown 到 html 的转换, 而是可以生成类似 rdoc 这样的拥有特定格式风格的查询文档
3.1 安装确保本地装有 node 环境:
$ npm install -g aglio3.2 生成 HTML
$ aglio -i api.md -o api.html四、本地调试
新建一个 statistics.md 文件, 输入如下内容:
FORMAT: 1A # Example API statistics ## 统计 [/statistics] ### 获取统计数据 [GET] + Response 200 (application/json) { "success": true, "err_code": "888888", "err_msg": "错误说明", "data": [{ "hour": "2016-10-31", "totalIncome": "1000.09", "totalRefund": "100.08", "incomeOrders": 70, "refundOrders": 10, "totalOrders": 80 }] }4.1 生成HTML文档
$ aglio -i statistics.md -o statistics.html
点击查看
4.2 创建 mock server前面安装的mock工具是drakov,创建mock服务的命令行如下:
$ drakov -f ./statistics.md -p 3000
如果你安装的是api-mock:
$ api-mock ./statistics.md --port 3000
当所有的都弄完以后,就可以访问http://localhost:3000/statistics,发送网络请求获取数据,无需等待,前后端同步进行,nice。
参考文档使用 API-Blueprint 编写 API 文档
api blueprint
用 API blueprint 生成优雅的 RESTful API 文档
API Blueprint Docker
API Blueprint
API Blueprint 指导手册
用 API blueprint 生成优雅的 RESTful API 文档
文章版权归作者所有,未经允许请勿转载,若此文章存在违规行为,您可以联系管理员删除。
转载请注明本文地址:https://www.ucloud.cn/yun/35804.html
摘要:之前虽然了解各种概念,但是自己捣鼓后,才算是真正的理解。只能把文档渲染成,但是不包括,所以需要配合。这里是启动脚本,看最后一行,定义了默认启动脚本。这个脚本负责监听,启动部署。如何使用这个项目已经放到了和上。 API Blueprint 上次介绍的 API Blueprint 解决方案 虽然不错,但是有一些问题: 部署麻烦,需要装不少东西 文档更新后不支持自动部署 没有权限控制 以...
前言 今天发现了一个很niubility的东西__API Blueprint__,先给出官网https://apiblueprint.org/。下面是官网给出的介绍: API Blueprint. A powerful high-level API description language for web APIs. 这个可以干什么呢?按照API Blueprint的语法(类似markdown),...
摘要:而则是主要用于接口缓存的一款。初始化完成后,将在当前目录生成文件。其它未在规则中的请求,将直接代理并缓存下来,而不进行转发。每条记录包含和两个属性,并且也是随机自动生成的。 概述 搜到这篇文章之前,相信你已对Mock Server及mock.js有一定的了解。简单概括,Mock Server即模拟服务器,用于模拟后端api服务。mock.js是国内的高云开发的一款json数据生成器,主...
阅读 1961·2021-09-26 10:19
阅读 3204·2021-09-24 10:25
阅读 1598·2019-12-27 11:39
阅读 1895·2019-08-30 15:43
阅读 631·2019-08-29 16:08
阅读 3475·2019-08-29 16:07
阅读 891·2019-08-26 11:30
阅读 1241·2019-08-26 10:41