使用apidoc 生成Restful web Api文檔

在項目開發過程當中，總會牽扯到接口文檔的設計與編寫，以前使用的都是office工具，寫一個文檔，總也是不夠漂亮和直觀。好在git上的開源大神提供了生成文檔的工具，so來介紹一下！
該工具是Nodejs的模塊，請務必在使用前安裝好nodejs環境！

---

工具名稱：apiDoc
Git地址：https://github.com/apidoc/apidoc
項目地址：http://apidocjs.com/
樣例項目：http://apidocjs.com/example_basic/
apoDoc是從源碼的註釋中生成RestFul api 文檔，樣子仍是蠻漂亮的……

本身寫了的ApiDoc文檔自動生成工具，避免每次寫完後手動執行生成代碼
http://blog.csdn.net/soslinken/article/details/50476384

支持的註釋樣式:
JavaDoc-Style

/** * This is a comment. */

CoffeeScript

###
This is a comment.
###

Elixir

@apidoc """ This is a comment. """

Erlang（%不是必須的）

%{
% This is a comment.
%}

Perl (Doxygen)

#**
# This is a comment.
#*

Python

""" This is a comment. """

Ruby

=begin This is a comment. =end

---

安裝apiDoc

npm install apidoc -g

使用npm命令安裝apidoc便可！

使用方式:
在命令行中輸入

apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

參數說明：
-f 文件過濾
使用正則表達式，表示哪些文件須要本轉換，不設置的狀況下，默認爲.cs .dart .erl .go .java .js .php .py .rb .ts 後綴的文件。

-i 代碼文件夾

-o 輸出Api文檔的路徑

-t 使用模板文件的路徑，能夠自定義輸出的模板

經常使用的命令格式以下:

apidoc -i myapp/ -o apidoc/

---

配置
無package.json文件時，須要在代碼文件夾的根目錄下，建立apidoc.json文件。

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1" }

在該文件中便可配置apidoc

有package.json文件時，在package.json文件中添加」apidoc」: { }屬性便可。

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": { "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" } }

配置屬性以下:
name：項目名稱
version：項目版本
description：項目介紹
title：瀏覽器顯示的標題內容
url：endpoints的前綴，例如https://api.github.com/v1
sampleUrl：若是設置了，則在api文檔中出現一個測試用的from表單
header
title：導航文字包含header.md文件
filename：markdown-file 文件名
footer
title：導航文字包含header.md文件
filename：markdown-file 文件名
order：用於配置輸出 api-names/group-names 排序，在列表中的將按照列表中的順序排序，不在列表中的名稱將自動顯示。

---

模板的配置:
在apidoc.json中或在package.json中添加template屬性，將對模板進行特殊設置
forceLanguage：生成指定語言的文檔，簡體中文僅需設置」zh-cn」，支持的語言：https://github.com/apidoc/apidoc/tree/master/template/locales
withCompare：是否啓用與舊版本的比較功能，默認爲true
withGenerator：是否輸出生成信息，默認爲true
jQueryAjaxSetup：設置Ajax請求的默認值,參見http://api.jquery.com/jquery.ajaxsetup/

---

我使用的配置以下:

{
  "name": "測試",
  "version": "0.0.1",
  "description": "API文檔測試",
  "title": "API文檔測試",
  "url" : "http://xxxxxxx",
  "sampleUrl" : "http://xxxxxxxx",
  "template":{ "forceLanguage":"zh-cn" } }

先來個demo試試：
在myapp文件夾下建立example.java

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

以後執行

apidoc -i myapp/ -o apidoc/

打開apidoc文件夾下的index.html便可看到效果。贊贊噠……

---

重頭戲來了，下面要講解一下apiDoc的註釋都是什麼含義

@api

@api {method} path [title]

使用該註釋的才能被識別成爲文檔的一塊內容

method：請求方法，參見https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods
path：請求路徑
title(可選)：標題

Example:

/** * @api {get} /user/:id */

@apiDefine

@apiDefine name [title]
                     [description]

定義重複內容，供其餘模塊引用

name：重複模塊名
title（可選）：標題
description（可選）：說明

Example1:

/** * @apiDefine MyError * @apiError UserNotFound The <code>id</code> of the User was not found. */

/** * @api {get} /user/:id * @apiUse MyError */

Example2:

/** * @apiDefine admin User access only * This optional description belong to to the group admin. */

/** * @api {get} /user/:id * @apiPermission admin */

@apiDescription

@apiDescription text

設置多行說明

text：多行說明內容

Example

/** * @apiDescription This is the Description. * It is multiline capable. * * Last line of Description. */

@apiError

@apiError [(group)] [{type}] field [description]

請求錯誤參數

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

Example:

/** * @api {get} /user/:id * @apiError UserNotFound The <code>id</code> of the User was not found. */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

錯誤返回信息樣例。

type（可選）：返回內容的格式
title（可選）：標題
example：樣例，能夠是多行文本

Example:

/** * @api {get} /user/:id * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */

@apiExample

@apiExample [{type}] title
            example

請求Api的測試樣例

{type}（可選）：請求方式類型
title：標題
example：樣例，能夠是多行文本

Example:

/** * @api {get} /user/:id * @apiExample {curl} Example usage: * curl -i http://localhost/user/4711 */

@apiGroup

@apiGroup name

定義Api的分組

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

Example:

/** * @api {get} /user/:id * @apiGroup User */

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

定義head參數

(group)（可選）：分組
{type}（可選）：類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：變量名
[field]：定義變量，並標記變量是可選項
=defaultValue（可選）：默認值
description（optional）：變量說明

Examples:

/** * @api {get} /user/:id * @apiHeader {String} access-key Users unique access-key. */

@apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

head參數樣例

{type}（可選）：請求方式類型
title：標題
example：樣例，能夠是多行文本

Example:

/** * @api {get} /user/:id * @apiHeaderExample {json} Header-Example: * { * "Accept-Encoding": "Accept-Encoding: gzip, deflate" * } */

@apiIgnore

@apiIgnore [hint]

忽略不發佈到文檔

hint（可選）：不發佈的緣由

Example:

/** * @apiIgnore Not finished Method * @api {get} /user/:id */

@apiName

@apiName name

定義api名稱

name：api名稱

Example:

/** * @api {get} /user/:id * @apiName GetUser */

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

定義請求Api的參數

(group)（可選）：分組
{type}（可選）：類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
{type{size}}（可選）：類型限定長度，例如：{string{..5}} 限定最大長度爲5個字符
{string{2..5}} 限定最短2個字符，最長5個字符
{number{100-999}} 限定數字在100-999之間
{type=allowedValues}（可選）：類型限定值，例如：{string=」small」}限定只容許傳遞small字符，
{string=」small」,」huge」} 限定只容許傳遞small或huge字符，
{number=1,2,3,99} 限定只容許傳1，2，3，99這四個數字
field：變量名
[field]：定義變量，並標記變量是可選項
=defaultValue（可選）：默認值
description（optional）：變量說明

Examples:

/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */

/** * @api {post} /user/ * @apiParam {String} [firstname] Optional Firstname of the User. * @apiParam {String} lastname Mandatory Lastname. * @apiParam {String} country="DE" Mandatory with default value "DE". * @apiParam {Number} [age=18] Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in users can post this. * In generated documentation a separate * "Login" Block will be generated. */

@apiParamExample

@apiParamExample [{type}] [title]
                   example

請求參數樣例

{type}（可選）：請求方式類型
title：標題
example：樣例，能夠是多行文本

Example:

/** * @api {get} /user/:id * @apiParamExample {json} Request-Example: * { * "id": 4711 * } */

@apiPermission

@apiPermission name

定義接口權限

name：權限名稱

Example:

/** * @api {get} /user/:id * @apiPermission none */

@apiSampleRequest

  
  
  
  

   
   
   
   
1
  
  
  
  
@apiSampleRequest url

設置測試請求form，若是在apidoc.json或package.json中設置過了sampleUrl，則默認請求地址爲，sampleUrl+apipath，設置這個標籤則重寫測試請求路徑

url：測試地址，
樣例
@apiSampleRequest http://www.example.com 改變測試地址
@apiSampleRequest /my_test_path 在apipath中加前綴
@apiSampleRequest off 不顯示測試請求from

Examples:
默認請求的地址是http://api.github.com/user/:id

Configuration parameter sampleUrl: "http://api.github.com"
/** * @api {get} /user/:id */

須要將測試地址修改成http://test.github.com/some_path/user/:id，則

Configuration parameter sampleUrl: "http://api.github.com"
/** * @api {get} /user/:id * @apiSampleRequest http://test.github.com/some_path/ */

當地址須要請求http://api.github.com/test/user/:id則

Configuration parameter sampleUrl: "http://api.github.com"
/** * @api {get} /user/:id * @apiSampleRequest /test */

不須要測試請求from

Configuration parameter sampleUrl: "http://api.github.com"
/** * @api {get} /user/:id * @apiSampleRequest off */

沒有設置sampleUrl時須要顯示測試請求from，並設置請求http://api.github.com/some_path/user/:id

Configuration parameter sampleUrl is not set
/** * @api {get} /user/:id * @apiSampleRequest http://api.github.com/some_path/ */

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

請求成功返回的參數

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

Example:

/** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

請求成功返回數據樣例

{type}（可選）：請求方式類型
title：標題
example：樣例，能夠是多行文本

Example:

/** * @api {get} /user/:id * @apiSuccessExample {json} Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } */

@apiUse

@apiUse name

使用在@apiDefine中定義的內容

name：在@apiDefine定義的name

Example:

/** * @apiDefine MySuccess * @apiSuccess {string} firstname The users firstname. * @apiSuccess {number} age The users age. */

/** * @api {get} /user/:id * @apiUse MySuccess */

@apiVersion

@apiVersion version

設定Api的版本號

version：版本號，格式(major.minor.patch)

Example:

/** * @api {get} /user/:id * @apiVersion 1.6.2 */

以上就是apiDoc的介紹！謝謝各位看官……

附上一個樣例

user.java

/** * @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":"註冊成功"} */

 /** * @api {POST} /login 用戶登陸 * @apiGroup Users * @apiVersion 0.0.1 * @apiDescription 用於用戶登陸 * @apiParam {String} userName 用戶名 * @apiParam {String} password 密碼 * @apiParamExample {json} 請求樣例： * ?userName=張三&password=11223344 * @apiSuccess (200) {String} msg 信息 * @apiSuccess (200) {String} code 0 表明無錯誤 1表明有錯誤 * @apiSuccess (200) {String} user 用戶信息 * @apiSuccess (200) {String} userId 用戶id * @apiSuccessExample {json} 返回樣例: * {"code":"0","msg":"登陸成功","userId":"fe6386d550bd434b8cd994b58c3f8075"} */

 /** * @api {GET} /users/:id 獲取用戶信息 * @apiGroup Users * @apiVersion 0.0.1 * @apiDescription 獲取用戶信息 * @apiSuccess (200) {String} msg 信息 * @apiSuccess (200) {int} code 0 表明無錯誤 1表明有錯誤 * @apiSuccess (200) {String} name 真實姓名 * @apiSuccess (200) {String} mobile 手機號 * @apiSuccess (200) {String} birthday 生日 * @apiSuccess (200) {String} email 郵箱 * @apiSuccess (200) {String} summary 簡介 * @apiSuccess (200) {String} recommendCode 個人推薦碼 * @apiSuccess (200) {String} idCardNo 身份證號 * @apiSuccess (200) {String} memberState 會員狀態 0普通用戶 1VIP 2帳戶凍結 * @apiSuccess (200) {String} address 家庭住址 * @apiSuccess (200) {String} money 帳戶現金 * @apiSuccessExample {json} 返回樣例: * { * "code": 0, * "msg": "", * "name": "真實姓名", * "mobile": 15808544477, * "birthday": "1990-03-05", * "email": "slocn@gamil.com", * "summary": "簡介", * "recommendCode": "個人推薦碼", * "idCardNo": "身份證號", * "memberState": 1, * "address": "家庭住址", * "money": "30.65" * } */


 /** * @api {POST} /users/:id 修改(完善)用戶信息 * @apiGroup Users * @apiVersion 0.0.1 * @apiDescription 修改(完善)用戶信息 * @apiParam (200) {String} [name] 真實姓名 * @apiParam (200) {String} [mobile] 手機號 * @apiParam (200) {String} [birthday] 生日 * @apiParam (200) {String} [email] 郵箱 * @apiParam (200) {String} [summary] 簡介 * @apiParam (200) {String} [idCardNo] 身份證號 * @apiParam (200) {String} [address] 家庭住址 * @apiSuccess (200) {String} msg 信息 * @apiSuccess (200) {int} code 0 表明無錯誤 1表明有錯誤 * @apiSuccessExample {json} 返回樣例: * {"code":"0","msg":"修改爲功"} */

這個樣例能夠直接生成，生成後便可看到apidoc的效果

2018年1月22日 更新

看到有不少人說中文亂碼的事情，今天特別更新說明一下

主要是 @apiGroup 不支持utf-8 字符串。僅支持ascii碼。因此不少使用者要麼只能用英文說明，要麼就放棄這個工具。

在官方有個辦法能夠實現utf-8字符串放置在@apiGoup 中。
代碼以下

/** * @apiDefine userApiStr 用戶接口文檔 */

/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup userApiStr */

說明
一、@apiDefine 必須放置在 /* …../中，也必須與引用變量的地方分開。
二、@apiGroup 後 放置的是 @apiDefine 定義的 變量名

其實本質上是定義了一個引用變量，這個變量支持utf-8。