基於RAML的API接口文檔管理

基於RAML的API接口文檔管理

什麼是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