歡迎關(guān)注微信公眾號：全棧工廠

本文主要參考

• ApiDoc官方文檔

最近項目開始接口測試氧骤，需要提供一份最新、最全的接口文檔,也許你覺得沒什么几于，但是如果我要求每個接口文檔都要像下面的例子一樣：

接口標題

接口描述

POST /request_api_url

請求頭參數(shù)列表:

請求體參數(shù)列表:

請求示例:

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

請求參數(shù)示例1:

{
    "body_param_1":"value1",
}

請求參數(shù)示例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版的喉刘，怎么樣瞧柔？小伙子，你有沒有感受到一絲絲的絕望睦裳？
如果我還告訴你現(xiàn)在需要整理的接口有160多個...

最開始考慮肩扛人挑的方式梳理文檔的我在整理了半天之后我就瘋了造锅，代碼注釋的不完整，需要人工核對實現(xiàn)邏輯廉邑，接口請求結(jié)果需要一個個跑請求來填寫哥蔚，這些本來在接口編寫或者接口修改時就可以完成的內(nèi)容，現(xiàn)在累加起來就像一個巨無霸工程蛛蒙。更可怕的是即使這次接口文檔梳理完成了糙箍，等到若干個月之后，接口文檔需要更新宇驾，然而你還需要這樣一個個去核對哪些接口做了修改倍靡，更新文檔！？紊帷塌西！

一捡需、apidoc簡介

apidoc是一個可以直接由源代碼中滴注釋生成api接口文檔的自動化文檔導(dǎo)出工具，并且支持目前流行的幾乎所有格式的注釋風格筹淫。該工具的源代碼目前托管于github(https://github.com/apidoc/apidoc)站辉，通過對該工具的使用，寡人目前總結(jié)的優(yōu)點主要有以下幾點：

① 文檔生成依賴注釋损姜，對源代碼幾乎沒有侵入饰剥；
② 規(guī)范化的注釋利于協(xié)同開發(fā)，并且如果接口有變動摧阅，更新注釋便等同于更新了接口文檔汰蓉；
③ 不同版本接口文檔對比功能，方便對同一接口的不同版本進行比較查看棒卷。

說的這幾點其實最主要的還是注釋和文檔的同步更新顾孽，相信幾乎所有的開發(fā)者在寫完代碼后寧愿去更新注釋也不愿意去更新接口文檔祝钢。

二、自動化導(dǎo)出HTML接口文檔

通過使用apidoc工具便可以直接導(dǎo)出HTML接口文檔：

2.1 安裝apidoc

apidoc通過npm安裝若厚，所以您需要先安裝nodejs或者npm工具拦英，安裝完npm之后運行一下命令：

 npm install apidoc -g

您也可以在docker環(huán)境中安裝，此處不再贅述测秸。

2.2 代碼注釋遵循apidoc風格

既然要使用apidoc導(dǎo)出文檔疤估，那自然要讓apidoc認識你的注釋，apidoc注釋規(guī)范可以參考官方文檔(http://apidocjs.com)乞封，寡人也對官方的文檔做了簡要翻譯注釋(【ApiDoc】官方文檔(翻譯))做裙，供大家參考。

2.3 運行apidoc 導(dǎo)出HTML文檔

運行apidoc前需要先添加一個配置文件apidoc.json,該配置文件的內(nèi)容官方文檔里有介紹肃晚，大致如下：

{
  "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主要命令參數(shù)如下：

通常情況下只需要指定源文件目錄锚贱、輸出文件目錄、配置文件目錄即可：

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

運行完成后关串，您便可以在output_dir目錄下看到生成的html文件拧廊，點擊index.html即可在瀏覽器查看接口文檔。

三晋修、自動化導(dǎo)出Markdown接口文檔

面對如此強大的apidoc工具吧碾，我一度以為可以通過修改輸出模板文件來導(dǎo)出markdown文件，但通過查看當前版本(0.17.6)源代碼墓卦，我發(fā)現(xiàn)apidoc在生成輸出文件的時候僅僅是將模板文件拷貝到輸出目錄下倦春，并沒有像我想象的那樣根據(jù)模板文件生成輸出文檔，apidoc所做的工作主要是通過讀取源代碼中的注釋落剪，解析生成一個api_data.json文件睁本，這個文件里面包含了所有從注釋中提取粗來的接口數(shù)據(jù)。所以接下來的工作便是根據(jù)這個api_data.json文件生成markdown文件即可忠怖。
幸運的是呢堰，GitHub上已經(jīng)有好心人為我們做了這個工作。

3.1 安裝apidoc-markdown

apidoc-markdown是一個根據(jù)apidoc輸出文件直接生成markdown文件的工具凡泣。首先我們需要安裝該工具：

npm install  apidoc-markdown -g

3.2 導(dǎo)出Markdown文檔

apidoc-markdown主要命令參數(shù)如下：

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

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

這樣我們便完成了接口文檔從HTML到Markdown文件的轉(zhuǎn)化。

3.3 添加自定義的markdown模板文件

由于該工具自帶的markdown模板并不是非常完美鞋拟，對于api_data.json文件中的字段并不是完全解析骂维，所以你需要自己分析api_data.json中的數(shù)據(jù)接口，完善markdown模板文件贺纲。該文件是EJS模板文件航闺，語法比較簡單，有需要的童鞋可以自行Google哮笆，另外您也可以下載該工具的源代碼来颤，修改里面自帶的模板文件也比較方便。

四稠肘、自動化導(dǎo)出PDF接口文檔

既然markdown文件都有了福铅，那么導(dǎo)出PDF文件不是更簡單了。在這里项阴，寡人推薦一個灰常好用的markdown離線編輯工具——Typora
Typora是一款離線輕量Markdown編輯器滑黔，該工具非常簡潔、易用(目前處于測試階段环揽，可免費使用)略荡。具體如何簡單、易用在這里就不做贅述了歉胶，大家可以自行下載體驗汛兜。其實最主要原因還是因為這個編輯器的導(dǎo)出PDF文件功能，該編輯器導(dǎo)出的pdf文件會根據(jù)markdown文件的目錄生成pdf的導(dǎo)航目錄通今，這一點對于文檔文件來說忒重要了Ｖ嗝！辫塌！

五漏策、總結(jié)

好了，至此任務(wù)基本上完成了臼氨，以后麻麻再也不用擔心我寫接口文檔啦掺喻！

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