一、概述

原文地址：https://pro.ant.design/docs/api-doc-cn

在日常開發中，往往是前後端分離的，這個時候約定好一套介面標準，前後端各自獨立開發，就不會被對方的技術難點給阻塞住，從而保證專案進度。

在 Ant Design Pro 中我們已經有了一套比較完善的 mock 功能，而 roadhog-api-doc 工具，則能夠從專案的 mock 資料中讀取介面資訊生成對應的文件，這樣就能夠更加清晰明瞭的展現專案的介面情況。

效果如下：Pro API Docs。

二、詳細

2.1、如何使用

npm install roadhog-api-doc -g

2,1.1、本地服務

進入到專案根目錄，執行：

roadhog-api-doc start [port]

就可以在當前專案跑起一個文件網站，但是前提是必須跟 Ant Design Pro 一樣是基於 roadhog 的專案，並且使用了資料 mock 功能，因為文件的資訊來源就是 mock 檔案。

需要額外注意的是，上面的 port 引數指的是當前本地的 roadhog 應用起的服務，如果指定了可以在本地直接點選訪問專案介面，沒有指定則會靜態化網路請求。

訪問：localhost:8001/api.html

2.1.2、靜態站點生成

專案根目錄，執行：

roadhog-api-doc build

會生成三個文件站點靜態檔案：api.html、api.js、api.css，你可以將其部署到自己的站點中供線上訪問，這裡的資料已經被靜態化（轉換網路請求為程式碼資料）。

2.1.3、書寫文件

通常來講，你無需額外加入任何依賴就可以生成文件，但是如果你需要對介面做出說明，需要按照以下格式對 roadhog mock 檔案進行修改：

npm install roadhog-api-doc --save-dev # 將 roadhog-api-doc 作為本地工具依賴安裝

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,
    },
  },
};

export default format(proxy);

其中：

• $desc: 介面說明

• $params: 介面引數說明，物件描述各個引數的意義

• $body: 資料返回結果，通常就是 mock 的資料

2.1.4、本地測試 mock 資料和真實埠

當啟動本地的 API Docs 站點以後，可以點選 send 按鈕傳送 POST 或者 GET 請求，並且返回值會在彈出框中顯示：

其中需要注意的是，如果啟動 API Docs 站點時，沒有加埠號，那麼這裡的返回資料是靜態資料，如果加了埠號並且本地也同時跑起了專案，那麼就會直接返回實際資料。

如果你想直接訪問線上的真實資料，那麼需要改寫當前專案的 .roadhog.mock.js，重定向到線上路徑。

可以通過訪問 roadhog-api-doc github 瞭解更多。