【ApiDoc】自動化匯出介面文件之HTML/Markdown/PDF實踐

本文主要參考

• ApiDoc官方文件

最近專案開始介面測試，需要提供一份最新、最全的介面文件,也許你覺得沒什麼，但是如果我要求每個介面文件都要像下面的例子一樣：

介面標題

介面描述

POST /request_api_url

請求頭引數列表:

名稱	型別	必填	說明
header_param_1	string	yes	引數描述
header_param_2	string	yes	引數描述

請求體引數列表:

名稱	型別	必填	說明
body_param_1	string	yes	引數描述
body_param_2	string	yes	引數描述 預設值:test
body_param_3	int	no	引數描述 預設值:1 可選值: 0,1,

請求示例:

curl -i -X POST -d body_param_1=value1&body_param_2=value2 http://localhost/request_api_url

請求引數示例1:

{
    "body_param_1":"value1",
}

請求引數示例2:

{
    "body_param_1":"value1",
    "body_param_2":"value2",
    "body_param_3":1
}

請求成功示例1:

{
    "status": "success",
    "data": {
      "key1": "value1",
    }
}

請求成功示例2:

{
    "status": "success",
    "data": {
      "key1": "value1",
      "key2": "value2",
      "key3": "key3",
      "update_time": 1509431405,
      "create_time": 1509431405
    }
}

請求錯誤示例1:

{
    "status": "failure",
    "error_message": {
        "error_code":403
          ...
    }
}

請求錯誤示例2:

{
    "status": "failure",
     "error_message": {
        "error_code":404
          ...
    }
}

怎麼樣？小夥子，你有沒有感受到一絲絲的繁瑣？
如果我還告訴你我不僅需要PDF版的，我還需要Markdown版的，還可能需要HTML版的，怎麼樣？小夥子，你有沒有感受到一絲絲的絕望？
如果我還告訴你現在需要整理的介面有160多個...

最開始考慮肩扛人挑的方式梳理文件的我在整理了半天之後我就瘋了，程式碼註釋的不完整，需要人工核對實現邏輯，介面請求結果需要一個個跑請求來填寫，這些本來在介面編寫或者介面修改時就可以完成的內容，現在累加起來就像一個巨無霸工程。更可怕的是即使這次介面文件梳理完成了，等到若干個月之後，介面文件需要更新，然而你還需要這樣一個個去核對哪些介面做了修改，更新文件！！！

面對這麼痛的痛點，幸運的是，早就有大神為我們鋪出了一條陽關大道——apidoc

一、apidoc簡介

apidoc是一個可以直接由原始碼中滴注釋生成api介面文件的自動化文件匯出工具，並且支援目前流行的幾乎所有格式的註釋風格。該工具的原始碼目前託管於github(https://github.com/apidoc/apidoc)，通過對該工具的使用，寡人目前總結的優點主要有以下幾點：

① 文件生成依賴註釋，對原始碼幾乎沒有侵入；
② 規範化的註釋利於協同開發，並且如果介面有變動，更新註釋便等同於更新了介面文件；
③ 不同版本介面文件對比功能，方便對同一介面的不同版本進行比較檢視。

說的這幾點其實最主要的還是註釋和文件的同步更新，相信幾乎所有的開發者在寫完程式碼後寧願去更新註釋也不願意去更新介面文件。

二、自動化匯出HTML介面文件

通過使用apidoc工具便可以直接匯出HTML介面文件：

2.1 安裝apidoc

apidoc通過npm安裝，所以您需要先安裝nodejs或者npm工具，安裝完npm之後執行一下命令：

 npm install apidoc -g

您也可以在docker環境中安裝，此處不再贅述。

2.2 程式碼註釋遵循apidoc風格

既然要使用apidoc匯出文件，那自然要讓apidoc認識你的註釋，apidoc註釋規範可以參考官方文件(http://apidocjs.com)，寡人也對官方的文件做了簡要翻譯註釋(【ApiDoc】官方文件(翻譯))，供大家參考。

2.3 執行apidoc 匯出HTML文件

執行apidoc前需要先新增一個配置檔案apidoc.json,該配置檔案的內容官方文件裡有介紹，大致如下：

{
  "name": "介面名稱",
  "version": "0.1.0",
  "description": "Api介面文件",
  "url" : "http://qa.api.test.com/",
  "sampleUrl": "http://qa.api.test.com/",
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

apidoc主要命令引數如下：

引數	描述
-f --file-filters	指定讀取檔案的檔名過濾正規表示式(可指定多個) 例如: apidoc -f ".*\\.js$" -f ".*\\.ts$" 意為只讀取字尾名為js和ts的檔案 預設值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不讀取的檔名過濾正規表示式(可指定多個) 例如:apidoc -e ".*\\.js$" 意為不讀取字尾名為js的檔案 預設:''
-i, --input	指定讀取原始檔的目錄 例如：apidoc -i myapp/ 意為讀取myapp/目錄下面的原始檔 預設值:./
-o, --output	指定輸出文件的目錄 例如：apidoc -o doc/ 意為輸出文件到doc目錄下 預設值:./doc/
-t, --template	指定輸出的模板檔案 例如:apidoc -t mytemplate/ 預設:path.join(__dirname, '../template/')(使用預設模板)
-c, --config	指定包含配置檔案(apidoc.json)的目錄 例如:apidoc -c config/ 預設:./
-p, --private	輸出的文件中是否包含私有api 例如:apidoc -p true 預設:false
-v, --verbose	是否輸出詳細的debug資訊 例如:apidoc -v true 預設:false
-h, --help	檢視幫助文件

通常情況下只需要指定原始檔目錄、輸出檔案目錄、配置檔案目錄即可：

  apidoc -i source_dir/ -c config_dir/ -o output_dir/

執行完成後，您便可以在output_dir目錄下看到生成的html檔案，點選index.html即可在瀏覽器檢視介面文件。

三、自動化匯出Markdown介面文件

面對如此強大的apidoc工具，我一度以為可以通過修改輸出模板檔案來匯出markdown檔案，但通過檢視當前版本(0.17.6)原始碼，我發現apidoc在生成輸出檔案的時候僅僅是將模板檔案拷貝到輸出目錄下，並沒有像我想象的那樣根據模板檔案生成輸出文件，apidoc所做的工作主要是通過讀取原始碼中的註釋，解析生成一個api_data.json檔案，這個檔案裡面包含了所有從註釋中提取粗來的介面資料。所以接下來的工作便是根據這個api_data.json檔案生成markdown檔案即可。
幸運的是，GitHub上已經有好心人為我們做了這個工作。

3.1 安裝apidoc-markdown

apidoc-markdown是一個根據apidoc輸出檔案直接生成markdown檔案的工具。首先我們需要安裝該工具：

npm install  apidoc-markdown -g

3.2 匯出Markdown文件

apidoc-markdown主要命令引數如下：

引數	描述
-p, --path	指定apidoc生成的文件目錄
-o, --output	指定輸出的markdown檔案路徑(包含檔名) 例如:apidoc-markdown -o output_dir/markdown_name.md
-t, --template	指定生成markdown檔案的模板檔案(EJS模板檔案) 預設:使用工具自帶的模板檔案

通常情況下，我們需要允許下面這樣的命令:

apidoc-markdown -p apidoc_dir -o doc/doc_markdown.md

這樣我們便完成了介面文件從HTML到Markdown檔案的轉化。

3.3 新增自定義的markdown模板檔案

由於該工具自帶的markdown模板並不是非常完美，對於api_data.json檔案中的欄位並不是完全解析，所以你需要自己分析api_data.json中的資料介面，完善markdown模板檔案。該檔案是EJS模板檔案，語法比較簡單，有需要的童鞋可以自行Google，另外您也可以下載該工具的原始碼，修改裡面自帶的模板檔案也比較方便。

四、自動化匯出PDF介面文件

既然markdown檔案都有了，那麼匯出PDF檔案不是更簡單了。在這裡，寡人推薦一個灰常好用的markdown離線編輯工具——Typora
Typora是一款離線輕量Markdown編輯器，該工具非常簡潔、易用(目前處於測試階段，可免費使用)。具體如何簡單、易用在這裡就不做贅述了，大家可以自行下載體驗。其實最主要原因還是因為這個編輯器的匯出PDF檔案功能，該編輯器匯出的pdf檔案會根據markdown檔案的目錄生成pdf的導航目錄，這一點對於文件檔案來說忒重要了！！！

五、總結

好了，至此任務基本上完成了，以後麻麻再也不用擔心我寫介面文件啦！

注：文中如有任何錯誤，請各位批評指正！