先聲明下，apidoc是基于注釋來生成文檔的，它不基于任何框架，而且支持大多數編程語言，為了springboot系列的完整性，所以標了個題。

一、apidoc簡介

apidoc通過在你代碼的注釋來生成api文檔的。它對代碼沒有侵入性，只需要你寫好相關的注釋即可，并且它僅通過寫簡單的配置就可以生成高顏值的api接口頁面。它基于node.js，所以你需要安裝node.js環境。node.js安裝，點擊這里。這里就不介紹。

二、準備工作

安裝完node.js安裝api.doc,它的項目源碼：https://github.com/apidoc/apidoc 。

通過命令安裝：

npm install apidoc -g

三、注釋怎么寫

• @api

@api {method} path [title]
method：請求方法，
path：請求路徑 
title(可選)：標題

• @apiDescription

@apiDescription text
text說明

• @apiError

@apiError [(group)] [{type}] field [description]
（group）（可選）：參數將以這個名稱分組，不設置的話，默認是Error 4xx 
{type}（可選）：返回值類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]} 
field：返回值字段名稱 
descriptionoptional（可選）：返回值字段說明

• @apiGroup

@apiGroup name

name：組名稱，也是導航的標題

更多注釋，參見官方文檔：http://apidocjs.com/#params

四、寫給栗子

首先寫配置文件

在項目的主目錄新建一個apidoc.json文件：

{
 "name": "example",
 "version": "0.1.0",
 "description": "A basic apiDoc example"
}

更多配置參考：http://apidocjs.com/#configuration

寫個注釋:

/**

* @api {POST} /register 注冊用戶

* @apiGroup Users

* @apiVersion 0.0.1

* @apiDescription 用于注冊用戶

* @apiParam {String} account 用戶賬戶名

* @apiParam {String} password 密碼

* @apiParam {String} mobile 手機號

* @apiParam {int} vip=0 是否注冊Vip身份 0 普通用戶 1 Vip用戶

* @apiParam {String} [recommend] 邀請碼

* @apiParamExample {json} 請求樣例：

* ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=

* @apiSuccess (200) {String} msg 信息

* @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤

* @apiSuccessExample {json} 返回樣例:

* {"code":"0","msg":"注冊成功"}

*/

用apidoc命令生成文檔界面

先cd到工程的外層目錄，并在外層目建個輸出文檔的目錄，我建的是docapi。

輸命令：

apidoc -i chapter4/ -o apidoc/

-i 輸入目錄 -o 輸出目錄

chapter4是我的工程名。

可以看到在apidoc目錄生成了很多文件:

打開index.html,可以看到文檔頁面:

服務端開發過程中，我們需要提供一份 API 接口文檔給 Web 端和移動端使用。實現 API 接口文檔編寫工作，有很多種方式，例如通過 Word 文檔編寫，或者通過 MediaWiki 進行維護。此外，還有比較流行的方式是利用 Swagger 自動化生成文檔。這里，筆者想分享另一個 Web API 文檔生成工具 apidoc。

apidoc 是通過源碼中的注釋來生成 Web API 文檔。因此，apidoc 對現有代碼可以做到無侵入性。此外，apidoc 可以支持多種語言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua。通過 apidoc 可以非常方便地生成可交互地文檔頁面。

開始入門

首先，我們需要 node.js 的支持。在搭建好 node.js 環境后，通過終端輸入 npm 命名進行安裝。

npm install apidoc -g

接著，我們還需要添加 apidoc.json 文件到項目工程的根目錄下。

這里，筆者主要演示 Java 注釋如何和 apidoc 結合使用。現在，我們先來看一個案例。

最后，我們在終端輸入 apidoc 命令進行文檔生成。這里，我們用自己的項目工程的根目錄替代 myapp/,用需要生成文檔的地址替代 apidoc/。

apidoc -i myapp/ -o apidoc/

例如，筆者的配置是這樣的。

apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/

代碼注釋

@api

@api 標簽是必填的，只有使用 @api 標簽的注釋塊才會被解析生成文檔內容。格式如下：

@api {method} path [title]

這里，有必要對參數內容進行講解。

@apiDescription

@apiDescription 對 API 接口進行描述。格式如下：

@apiDescription text

@apiGroup

@apiGroup 表示分組名稱，它會被解析成一級導航欄菜單。格式如下：

@apiGroup name

@apiName

@apiName 表示接口名稱。注意的是，在同一個 @apiGroup 下，名稱相同的 @api 通過 @apiVersion 區分，否者后面 @api 會覆蓋前面定義的 @api。格式如下：

@apiName name

@apiVersion

@apiVersion 表示接口的版本，和 @apiName 一起使用。格式如下：

@apiVersion version

@apiParam

@apiParam 定義 API 接口需要的請求參數。格式如下：

這里，有必要對參數內容進行講解。

類似的用法，還有 @apiHeader 定義 API 接口需要的請求頭，@apiSuccess 定義 API 接口需要的響應成功，@apiError 定義了 API 接口需要的響應錯誤。

這里，我們看一個案例。

此外，還有 @apiParamExample，@apiHeaderExample， @apiErrorExample，@apiSuccessExample 可以用來在文檔中提供相關示例。

@apiPermission

@apiPermission 定義 API 接口需要的權限點。格式如下：

@apiPermission name

此外，還有一些特別的注解。例如 @apiDeprecated 表示這個 API 接口已經廢棄，@apiIgnore 表示忽略這個接口的解析。關于更多的使用細節，可以閱讀官方文檔：http://apidocjs.com/#demo

完整的案例

最后，我們用官方的案例，講解下一個完整的配置。

首先，配置 apidoc.json，內容如下：

接著，我們配置相關的 Java 源碼注釋。

然后，執行命名生成文檔。

生成的頁面，如下所示。

（完）

pidoc可以根據規定的格式的代碼注釋生成api接口靜態html網頁文檔說明文檔，大部分主流語言java javascript php coffeescript erlang perl python ruby等，對于多個團隊開發來說，非常有幫助。

下載包安裝

https://nodejs.org/dist/v4.4.4/

配置path（注意解壓路徑）

注意目錄(/tmp/node-v4.4.4-linux-x64)

配置/etc/profile文件：

export NODE_HOME=/tmp/node-v4.4.4-linux-x64

export PATH=$PATH:$NODE_HOME/bin

export NODE_PATH=$NODE_HOME/lib/node_modules

注：配置全局環境，如果在/etc/profile中配置，那么需要每次登陸后source一下，如果想長久有效，請在/etc/bashrc中配置

驗證安裝

node -v

npm -v

全局安裝apidoc

npm install apidoc -g

驗證安裝

apidoc -v

配置apidoc.json

{

"name": "WayBill 接口文檔",

"version": "1.0.0",

"description": "接口模塊，向其他模塊提供數據的訪問",

"title": "xxxxx模塊1.0接口",

"private": true,

"sampleUrl": " "

}

apidoc文檔注釋規范（見官網）

http://apidocjs.com/

執行生成命令

apidoc -i app/Http/Controllers -o public/doc

參考文檔：

http://apidocjs.com/

https://github.com/apidoc/apidoc