歡迎關注微信公眾號：全棧工廠
本文主要參考
最近項目開始接口測試，需要提供一份最新、最全的接口文檔,也許你覺得沒什么，但是如果我要求每個接口文檔都要像下面的例子一樣：
接口標題
接口描述
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)，通過對該工具的使用，寡人目前總結的優(yōu)點主要有以下幾點：
① 文檔生成依賴注釋，對源代碼幾乎沒有侵入；
② 規(guī)范化的注釋利于協同開發(fā)，并且如果接口有變動，更新注釋便等同于更新了接口文檔；
③ 不同版本接口文檔對比功能，方便對同一接口的不同版本進行比較查看。
說的這幾點其實最主要的還是注釋和文檔的同步更新，相信幾乎所有的開發(fā)者在寫完代碼后寧愿去更新注釋也不愿意去更新接口文檔。
二、自動化導出HTML接口文檔
通過使用apidoc工具便可以直接導出HTML接口文檔：
2.1 安裝apidoc
apidoc通過npm安裝，所以您需要先安裝nodejs或者npm工具，安裝完npm之后運行一下命令：
npm install apidoc -g
您也可以在docker環(huán)境中安裝，此處不再贅述。
2.2 代碼注釋遵循apidoc風格
既然要使用apidoc導出文檔，那自然要讓apidoc認識你的注釋，apidoc注釋規(guī)范可以參考官方文檔(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)源代碼，我發(fā)現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的導航目錄，這一點對于文檔文件來說忒重要了?。?！
五、總結
好了，至此任務基本上完成了，以后麻麻再也不用擔心我寫接口文檔啦！
注：文中如有任何錯誤，請各位批評指正！
