roadhog-api-doc 玩法介紹

最近工做中遇到了排期比較緊張的項目，先後端分離並行開發成爲必然選擇。所謂先後端分離，即約定好一套接口標準，先後端各自獨立開發，就不會被對方的技術難點給阻塞住，從而保證項目進度。這樣的並行開發看似美好，實際使用起來也遇到了很多痛點:

1. 在聯調測試中，接口不穩定，甚至約定接口字段變化的現象時有發生。直接反應是頁面報錯或顯示不正常，比較難快速定位問題。
2. 約定的接口老是開後端開發本身約定，隻言片語或零散的json文件，不能造成文檔，不利於維護與交接。

項目主要使用了組件庫ant-design.以及基於此的中臺前端解決方案 ant-design-pro. 該解決方案底層工具使用roadhog，該工具除了包裝webpack，webpack-dev-server 完成構建,和開發中的自動同步構建，還增長了代理轉發的功能，經過代理請求就可以輕鬆處理數據模擬的功能。使得在項目中能夠輕鬆集成模擬數據。

固然只是使用模擬數據仍是不夠的，使用roadhog-api-doc自動生成文檔工具，經過讀取假數據配置文件，能夠自動生成文檔。恰當使用配置，指定ip，端口，還能夠在文檔上直接發起請求訪問真實數據，本身寫個循環腳本就能夠批量測試接口啦。糟糕~ 是心動的感受。

前戲這麼久，終於進入正題了。下面進入使用攻略環節。

基本使用

roadhog-api-doc 主要是靠讀取 .roadhog.mock.js文件生成文檔。全部的mock數據都要寫在這裏。形式以下

import { postRule } from './mock/rule';
import { format } from 'roadhog-api-doc';
const proxy = {
  'GET /api/currentUser': {
    // 接口描述
    $desc: "獲取當前用戶接口",
    // 接口參數
    $params: {
      pageSize: {
        desc: '分頁',
        exp: 2,
      },
    },
    // 接口返回
    $body: {
      name: 'momo.zxy',
      avatar: imgMap.user,
      userid: '00000001',
      notifyCount: 12,
    },
  },
  'POST /api/rule': {
    $params: {
      pageSize: {
        desc: '分頁',
        exp: 2,
      },
    },
    $body: postRule,
  },
};

// format 函數用於保證本地的模擬正常，若是寫了文檔，這個函數轉換是必要的
export default format(proxy);

生成結果以下

文檔中請求地址，參數，包羅萬象。經過在mock接口中增長描述字段，就能夠直接在文檔中顯示了。點擊 send 按鈕,及發送請求。彈框輸出請求結果
使用 roadhog-api-doc start [port] 即啓動服務，指定端口，至關於開發環境，自動監控文件變化刷新頁面
使用 roadhog-api-doc build [port] 構建文檔，輸出到dist目錄，生成 api.html, api.js, api.css 三個文件

進階使用

輸出了api文檔，可是還想要請求真實環境地址，集中測試接口怎麼辦？
看了源碼後發現，請求地址的ip部分寫死了 localhost,只有端口可變。在lib/目錄下，源碼以下

const configContent = `
  export default {
    port: "${projectServerPort}",
    docPort: "${port}",
    isStatic: ${isStatic},
  }
  `;

    fs.writeFileSync(path.join(tempDir, './src/config.js'), configContent, 'utf-8');

    if (projectServerPort) {
      const mockjsContent = `
export default {
  'GET /api/*': 'http://localhost:${projectServerPort}/',
  'POST /api/*': 'http://localhost:${projectServerPort}/'
};
  `;
      fs.writeFileSync(path.join(tempDir, './.roadhogrc.mock.js'), mockjsContent, 'utf-8');
    }

projectServerPort是命令行輸入的端口號，咱們想要修改ip，須要修改一下源碼。將localhost 改成參數，在命令行中輸入，指定IP和端口號，就能夠自由發起請求了。
修改代碼

const mockjsContent = `
export default {
  'GET /api/*': '${projectIP}:${projectServerPort}/',
  'POST /api/*': '${projectIP}:${projectServerPort}/'
};

啓動命令改成
roadhog-api-doc start [port] [ip]
roadhog-api-doc build [port] [ip]

須要注意的是，start命令和build命令分別對應兩個執行文件 start.js build.js 兩個文件都要修改。

總結

roadhog-api-doc 的實現原理很簡單，就是靠讀取配置文件實現一個簡單的頁面。在ant-design-pro中，配合roadhog一塊兒使用,可使用一套mock數據，既可用於前端開發，又可生成接口文檔。一次修改，兩邊同步，很是便捷。不用特別維護接口文檔，爲開發省了很多力氣，也避免了接口文檔由於年久失修而被丟棄的命運。