Spring項目集成apidoc生成api接口文檔

一、背景需求

 JavaWeb/spring項目寫成的api接口，需要自動生成api文檔，甚至需要在線測試接口。考慮實現的方案有swagger，apidoc，spring rest docs。在之后的項目都有一一嘗試，最終還是覺得apidoc的方式比較合適，雖然有一些問題（針對在線測試方面），但可以進行定制修復並解決。

二、方案對比

1.現在大家普遍使用的是swagger結合springmvc來生成api接口文檔，對比apidoc，swagger有一個明顯的劣勢，便是返回的響應，無法生成文檔描述，即無法描述響應體的數據結構，這對前后端對接，或者是與移動端/其他端對接來說，需要耗費更多的交流成本，溝通成本，即不可能每個接口都通過實際調用后，看返回實體獲悉響應參數。針對后端改動響應體這種情況，又會導致新的問題存在。

 

2.spring rest docs，這是spring體系里提供的一種接口生成框架，基於mockmvc編寫單元測試，單元測試通過即可生成可供閱讀的接口文檔。這種生成方式需要編寫詳細的測試單元，並且稍微一點出錯便導致編譯不通過，對於程序的嚴謹有一定幫助，但又犧牲一些時間，並且最終生成的文檔是基於測試用例數據，沒有類似swagger和apidoc的在線測試功能。

 

3.apidoc，通過注釋，生成接口文檔，不像swagger和spring rest docs嵌入在代碼中，僅僅是通過注釋而已。缺點是在線測試功能有些問題，不支持文件表單，但這些缺陷都是可以彌補的，可通過再編程，重新定制源碼實現，基於handlebars.js。

三、環境准備

1.安裝node.js，

官網：https://nodejs.org/en/點擊打開鏈接；windows64位下載地址https://nodejs.org/dist/v8.9.4/node-v8.9.4-x64.msi下載；

Linux 上安裝 Node.js

參考地址：https://www.runoob.com/nodejs/nodejs-install-setup.html

直接使用已編譯好的包

1.1 Node 官網已經把 linux 下載版本更改為已編譯好的版本了，我們可以直接下載解壓后使用：

# wget https://nodejs.org/dist/v10.9.0/node-v10.9.0-linux-x64.tar.xz    // 下載
# tar xf  node-v10.9.0-linux-x64.tar.xz       // 解壓
# cd node-v10.9.0-linux-x64/                  // 進入解壓目錄
# ./bin/node -v                               // 執行node命令 查看版本

 v10.9.0

1.2 解壓文件的 bin 目錄底下包含了 node、npm 等命令，我們可以使用 ln 命令來設置軟連接：

ln -s /software/node-v10.9.0-linux-x64/bin/npm   /usr/local/bin/ 
ln -s /software/node-v10.9.0-linux-x64/bin/node   /usr/local/bin/

1.3環境配置

vim /etc/profile

export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

source  /etc/profile

 

1.4 再輸入npm -v 或者node -v 就能看到版本號啦~

 

 

 

2.安裝apidoc，

命令行下，輸入npm install apidoc -g，參考官網：http://apidocjs.com/#install 點擊打開鏈接

npm install apidoc -g

  2.1 ln 命令來設置apidoc軟連接：

ln -s /software/node-v10.9.0-linux-x64/bin/apidoc  /usr/local/bin/

2.2 安裝完畢，可在命令下使用apidoc -h測試是否安裝成功

apidoc -v

 

 

四、整合項目使用

1.項目根路徑下建立apidoc.json文件，配置好基本的文檔信息。

 

{
  "name": "API文檔",
  "version": "1.0.0",
  "description": "開發技術接口文檔",
  "title": "API文檔",
  "url" : "http://localhost:8080/test",
  "sampleUrl":"http://localhost:8080/test"
}

 

 

 

 

 2.demo 目錄下添加demo.js編寫接口文檔內容，內容也可寫在java接口前面部分

/**
 * @apiDefine A9999DemoInterface 風險預警應急中心
 */


/**
 * @api {GET} /app/api/getNewestDate 1-1 獲取最新有數據的日期
 * @apiName getNewestDate
 * @apiGroup A9999DemoInterface
 * @apiDescription 獲取最新有圖片的日期
 * @apiParam {String} token 比如xxxxxx_grand
 * @apiVersion 0.0.1
 * @apiSuccessExample {JSON} Success-Response:
{
    "code": 0,
    "msg": "success",
    "data": String // 日期
}
*/

/**
 * @api {GET} /app/api/getRadarPicCount 1-2 獲取指定日期的三個月內的每日數據次數
 * @apiName getRadarPicCount
 * @apiGroup A9999DemoInterface
 * @apiDescription  獲取指定日期的三個月內的每日數據次數
 * @apiParam {String} addtime 當前日期三個月內的數據次數
 * @apiParam {String} token 比如xxxxxx_grand
 * @apiVersion 0.0.1
 * @apiParamExample  {json} Request-Example:
 *     {
          "addtime":"2020-01-18"
       }
 * @apiSuccess (200) {Object} data 返回數據格式見下面json對象及備注
 * @apiSuccessExample {JSON} Success-Response:
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "addtime":"2020-01-18", //雷達預警時間
            "radarCount": "500112"  //次數
        }, ....
    ]
}
*/

或者如下這種，兩種都支持

 

 

 3，把項目拷貝到apidoc所在系統的linux目錄中

 

 

 5，生成apidoc文檔，apidoc -i ./ -o ./src/main/webapp/WEB-INF/doc

 

apidoc -i /software/manualPictrue/ -o /software/apache-tomcat-8.0.53-9100/webapps/apidoc/ 

重要參數：

 

參數	描述
-f，--file-filters	RegEx-Filter選擇要解析的文件（可以使用許多-f）。默認.cs .dart .erl .go .java .js .php .py .rb .ts。 示例（僅解析.js和.ts文件）： apidoc -f ".*\\.js$" -f ".*\\.ts$"
-i，-輸入	輸入/源目錄名。項目文件的位置。就是需要生成文檔的注釋文件所在目錄，會從內部尋找。 例： apidoc -i myapp/
-o，-輸出	輸出目錄名。放置生成的文檔的位置。 例：目錄我讓他生成在我此台主機的tomcat下面，他生成目錄后我就可以直接通過tomcat訪問接口文檔 apidoc -o /software/apache-tomcat-8.0.53-9100/webapps/apidoc/
-t，-模板	使用模板輸出文件。您可以創建和使用自己的模板。 例： apidoc -t mytemplate/

 6.訪問接口文檔。