基于RAML的API接口文档管理

逃离我推掉我的手 2022-01-31 04:41 476阅读 0赞

# 基于RAML的API接口文档管理 #

### 文章目录 ###

*  基于RAML的API接口文档管理
 *   *  什么是RAML
     *  怎么使用RAML
     *   *  设计
         *  构建&测试（mock server）
         *  文档
         *  扩展
     *  一个例子
     *   *  RAML文件
         *  文档

## 什么是RAML ##

`RAML(RESTful API Modeling Language)`，是一种建模语言，`RAML`定义好API的输入输出等属性后，可以使用不同的工具或方法生成API文档、构建mock server等，实现一次定义多处使用。

## 怎么使用RAML ##

![在这里插入图片描述][20190515170222379.png]

*  设计：RAML使用标准的yaml格式，使用方法参考：[RAML 1.0][] [使用RAML描述API文档信息的一些用法整理][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后可返回相应的结果，并且支持参数检查：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70 1]

### 文档 ###

`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][http_192.168.20.100_dbaas-mysql-api_exampleApi.html] 即可看到如下文档：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70 2]

### 扩展 ###

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

![img][]

[20190515170222379.png]: /images/20220131/e85e31adbfa846e88a432efad07a9d81.png
[RAML 1.0]: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/
[RAML_API]: https://www.cnblogs.com/darrenji/p/5198524.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70]: /images/20220131/ce0a24d7c1f6431a90ab3eb769a012d0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70 1]: /images/20220131/f53bdfa77eb54fc88678a37b0ecedb66.png
[http_192.168.20.100_dbaas-mysql-api_exampleApi.html]: http://192.168.20.100/dbaas-mysql-api/exampleApi.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0NMX1lE_size_16_color_FFFFFF_t_70 2]: /images/20220131/08c4067673f64995abd590a3de09a9d7.png
[json schema]: https://blog.csdn.net/silence_xiao/article/details/81303935
[img]: