ant design pro （十五）advanced 使用 API 文檔工具

一、概述

原文地址：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 了解更多。