平常工做記錄——JAVA中APIDOC的應用

1、APIDOC是什麼？

簡單通俗點說，apidoc是一款自動生成API接口文檔的工具。它支持多種語言的接口文檔生成，如C#、Java、JavaScript、PHP、Python等，詳情可參考官方文檔說明。java代碼中能夠經過註解來實現apidoc。

2、APIDOC安裝

　　1.由於apidoc依賴於node.js，因此首先要安裝node.js

• 安裝包下載

• 安裝教程

 2. 安裝apidoc

cmd打開運行命令框，輸入命令npm install apidoc -g便可安裝。

使用命令apidoc -h可驗證是否安裝成功。

 3、APIDOC使用

 1. 配置apidoc.json

在項目中建立apidoc.json文件，位置建議在項目根目錄(src目錄平級)，也可自選。

apidoc.json內容示例以下：

1 {
2   "name": "項目名稱",
3   "version": "項目版本",
4   "description": "項目描述",
5   "title": "瀏覽器標題",
6   "url" : "api路徑前綴，會自動拼接到@api 路徑前，能夠設置爲空串"
7 }

 具體參數名配置及含義可參考官方文檔

中文參考文檔

 2. 接口增長apidoc註解

具體參數名配置及含義可參考官方文檔

中文參考文檔

　　3. 生成接口文檔

cmd打開運行命令框，cd到apidoc.json目錄下，使用apidoc -i src/ -o apidoc/生成HTML格式接口文檔 

指令參數詳情列表：

參數	描述
-h, --help	查看幫助文檔
-f --file-filters	指定讀取文件的文件名過濾正則表達式(可指定多個)例如: apidoc -f 「.*\.js"−f".∗.ts " -f ".*\\.ts"−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