基于RAML的API接口文档管理
基于RAML的API接口文档管理
文章目录
- 基于RAML的API接口文档管理
- 什么是RAML
- 怎么使用RAML
- 设计
- 构建&测试（mock server）
- 文档
- 扩展
- 一个例子
- RAML文件
- 文档
什么是RAML
RAML(RESTful API Modeling Language)，是一种建模语言，RAML定义好API的输入输出等属性后，可以使用不同的工具或方法生成API文档、构建mock server等，实现一次定义多处使用。
怎么使用RAML
- 设计：RAML使用标准的yaml格式，使用方法参考：RAML 1.0 使用RAML描述API文档信息的一些用法整理，你可以快速的构造你的API，并以人类友好的格式将它呈现出来。它涵盖了一些重要设计的最佳实践，如建模、模式、模板以及代码重用。；
- 构建：一旦设计好你的API，你就可以借助一些开发工具，将设计好的静态API文档，变成一个服务器端来提供服务（mock server）；
- 测试：引入单元测试可以有效地保证API实现的正确性，你可以通过运行一些脚本来测试你服务端是否涵盖了你设计好的API；
- 文档：Raml可以帮助你脱离同步维护一份额外文档的痛苦。RAML是一门API描述语言，所以你的API一旦被描述，它就是一份现成的API文档。你可以借助一些工具将它生成可视化的文档；
- 共享：你可以借助一个基本的JavaScript来生成一些交互式工具（API Consoles或API Nodebooks），这样其他开发者可以使用标准格式与你的维护团队进行交流。
设计
IDEA插件，插件名称RAML Plugin For IntelliJ，安装插件后，可以直接创建.raml文件，支持yaml文件语法高亮和提示，当然还有其他IDE工具和文本编辑工具的插件。
构建&测试（mock server）
osprey-mock-service
可以使用osprey-mock-service工具快速搭建基于raml文件的mockserver：
npm i -g install osprey-mock-service
osprey-mock-service -f exampleApi.raml -p 8022
访问raml文件定义的API后可返回相应的结果，并且支持参数检查：
文档
raml2html
如果在RAML文件定义清楚，其实可以不要文档，直接看RAML文档即可，但为了更加直观，可以使用raml2html工具生成静态的html文件，然后本地访问或搭建静态http服务器访问；
npm i -g raml2html
raml2html exampleApi.raml > /var/www/html/dbaas-mysql-api/exampleApi.html
如果在20.100访问http://192.168.20.100/dbaas-mysql-api/exampleApi.html 即可看到如下文档：
扩展
RAML文件以及json schema都有不同语言的解析器，完全可以基于这些解析器开发属于自己的一套流程。
一个例子
例子中使用到的raml2html和osprey-mock-service都是nodejs家族的工具。
RAML文件
先写一个完整的raml文件（文件名后缀.raml），这里只使用基础语法，更高级的语法请参考github上的RAML手册：
#%RAML 1.0
---
title: MySQL备份相关 API
baseUri: http://192.168.20.100:8080/dbaasMariadb/backup
version: v1
/create:
post:
description: 创建备份任务
body:
application/json:
schema: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "create_param",
"required": true,
"properties": {
"dbServiceId": {"type": "string","required": true, "description": "mysql服务ID"},
"backupHostId": {"type": "string","required": true, "description": "备份主机ID"},
"backupType": {"type": "string","required": true, "description": "备份类型"},
"backupCron": {"type": "string","required": true, "description": "cron表达式"},
"backupDesc": {"type": "string","required": true, "description": "cron表达式描述"},
"backupDir": {"type": "string","required": true, "pattern": "^\/$", "description": "备份路径，目前只能是/"}
}
}
example: |
{
"dbServiceId": "05dbbc3f-2781-43bd-9f51-bc826800192f",
"backupHostId": "41a66359-916e-4cd0-ae23-74ec7e425bed",
"backupType": "xtrabackup全备",
"backupCron": "0 0 5 * * ?",
"backupDesc": "每天，05:00",
"backupDir": "/"
}
responses:
201:
body:
application/json:
example: |
{
"code": "1000",
"msg": "操作成功",
"data": null
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
/list:
get:
description: 备份任务列表
queryParameters:
clusterId:
description: 集群ID
type: string
required: true
pageSize:
description: 每页条数
type: integer
minimum: 1
required: true
pageNum:
description: 页码
type: integer
minimum: 1
required: true
responses:
200:
body:
application/json:
example: |
{
"code": "1000",
"msg": "操作成功",
"data": {
"pageSize": 15,
"pageNum": 1,
"pages": 4,
"startRow": 0,
"endRow": 15,
"total": 57,
"rows": [{
"id": 1,
"clusterId": "1bc67f13-3777-4072-bd5c-cb63f4bff50f",
"dbServiceId": "05dbbc3f-2781-43bd-9f51-bc826800192f",
"dbServiceName": "testdb",
"dbPort": 3306,
"hostId": "01c58a1b-92da-4d7a-835b-91035bc8e302",
"hostName": "dev1",
"hostIp": "192.168.20.81",
"backupHostId": "41a66359-916e-4cd0-ae23-74ec7e425bed",
"backupHostName": "localhost.domain",
"backupHostIp": "192.168.20.100",
"backupType": "xtrabackup全备",
"backupCron": "0 0 5 * * ?",
"backupDesc": "每天，05:00",
"createTime": "2019-04-24 05:00:00",
"updateTime": "2019-04-24 05:00:01"
}]
}
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
/update:
post:
description: 更新备份任务
body:
application/json:
schema: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "update_param",
"required": true,
"properties": {
"id": {"type": "integer", "required": true, "description": "备份任务ID"},
"dbServiceId": {"type": "string","required": true, "description": "mysql服务ID"},
"backupHostId": {"type": "string","required": true, "description": "备份主机ID"},
"backupType": {"type": "string","required": true, "description": "备份类型"},
"backupCron": {"type": "string","required": true, "description": "cron表达式"},
"backupDesc": {"type": "string","required": true, "description": "cron表达式描述"},
"backupDir": {"type": "string","required": true, "pattern": "^\/$", "description": "备份路径，目前只能是/"}
}
}
responses:
201:
body:
application/json:
example: |
{
"code": "1000",
"msg": "操作成功",
"data": null
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
/delete:
post:
description: 删除备份任务
body:
application/json: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "delete_param",
"required": true,
"properties": {
"id": {"type": "integer", "required": true, "description": "备份任务ID"}
}
}
responses:
201:
body:
application/json:
example: |
{
"code": "1000",
"msg": "操作成功",
"data": null
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
/options:
get:
description: 备份任务下拉列表
queryParameters:
clusterId:
description: 集群ID
type: string
required: true
responses:
200:
body:
application/json:
example: |
{
"code": "1100",
"data": {
"backupType": [
{"value": "xtrabackup全备", "label": "xtrabackup增备"}
],
"dbServiceId": [
{"value": "41a66359-916e-4cd0-ae23-74ec7e425bed", "label": "192.168.20.81:3306(master)"},
{"value": "41a66359-916e-4cd0-ae23-74ec7e425bef", "label": "192.168.20.85:3306(slave)"}
],
"backupHostId": [
{"value": "41a66359-916e-4cd0-ae23-74ec7e425bed", "label": "192.168.20.110"},
{"value": "41a66359-916e-4cd0-ae23-74ec7e425bef", "label": "192.168.20.120"}
]
}
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
/execute:
post:
description: 执行备份任务
body:
application/json:
schema: |
{
"type": "object",
"$schema": "http://json-schema.org/draft-03/schema",
"id": "execute_param",
"required": true,
"properties": {
"id": {"type": "integer", "required": true, "description": "备份任务ID"}
}
}
responses:
201:
body:
application/json:
example: |
{
"code": "1000",
"msg": "操作成功",
"data": null
}
500:
body:
application/json:
example: |
{
"code": "1100",
"msg": "操作失败",
"data": null
}
这就是一个完整的备份相关的raml定义文件。
文档
20.100有一个httpd服务器，将文档生成到/var/www/html/目录或其子目录下都可直接在浏览器访问
执行raml2html backup.raml > /var/www/html/dbaas-mysql-api/backup.html
访问：192.168.20.100/dbaas-mysql-api/backup.html
