Web API文檔生成工具apidoc

apidoc能夠根據代碼註釋生成web api文檔，支持大部分主流語言java javascript php coffeescript erlang perl python ruby go...，相對而言，web接口的註釋維護起來更加方便，不須要額外再維護一份文檔。

apidoc從註釋生成靜態html網頁文檔，不只支持項目版本號，還支持api版本號。

安裝

主頁: http://apidocjs.com
github: https://github.com/apidoc/apidoc
可使用npm install apidoc -g進行安裝，目前0.12.x/4.0均可以使用。

apidoc支持Grunt，主頁 https://github.com/apidoc/grunt-apidoc

1. 在項目中使用npm install grunt-apidoc --save-dev安裝。
2. 在Gruntfile.js添加grunt.loadNpmTasks('grunt-apidoc');。
3. 配置grunt task

apidoc: {
      myapp: {
        src: "app/",
        dest: "apidoc/"
      }
}

 

// 在sails中2和3能夠直接添加一個task

module.exports = function(grunt) {

    grunt.config.set('clean', {
      apidoc: {
        myapp: {
          src: "app/",
          dest: "apidoc/"
        }
      }
    });

    grunt.loadNpmTasks('grunt-apidoc');
};

 

用法

能夠在shell中執行apidoc -h就能夠看到不少用法。

下面講講經常使用的幾個參數。

// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"

-i 表示輸入，後面是文件夾路徑
-o 表示輸出，後面是文件夾路徑
默認會帶上-c，在當前路徑下尋找配置文件(apidoc.json)，若是找不到則會在package.json中尋找 "apidoc": { }
-f 爲文件過濾，後面是正則表達式，示例爲只選着js文件
  與-f相似，還有一個 -e 的選項，表示要排除的文件/文件夾，也是使用正則表達式
若是項目輸入和輸出穩定，能夠編輯Makefile保存命令，例如：

docs:
    @apidoc -i api/ -o doc/apidoc

 

以後使用make docs便可生成/更新api文檔。

配置

項目配置

apidoc.json示例：

{
  "name" : "mysails",
  "version": "1.0.0",
  "title": "mysails", // 瀏覽器標題
  "description": "xun's test project"
}

 

若是放入package.json中，相同的字段能夠直接使用package.json的定義，額外的字段放入apidoc下

{
  "name": "mysails",
  "private": true,
  "version": "1.0.0",
  "description": "xun's test project",
  "apidoc": {
    "title": "mysails"
  },
  ...
}

 

代碼註釋

apidoc支持以下關鍵字

@api {method} path [title]
  只有使用@api標註的註釋塊纔會在解析以後生成文檔，title會被解析爲導航菜單(@apiGroup)下的小菜單
  method能夠有空格，如{POST GET}
@apiGroup name
  分組名稱，被解析爲導航欄菜單
@apiName name
  接口名稱，在同一個@apiGroup下，名稱相同的@api經過@apiVersion區分，否者後面@api會覆蓋前面定義的@api
@apiDescription text
  接口描述，支持html語法
@apiVersion verison
  接口版本，major.minor.patch的形式

@apiIgnore [hint]
  apidoc會忽略使用@apiIgnore標註的接口，hint爲描述
@apiSampleRequest url
  接口測試地址以供測試，發送請求時，@api method必須爲POST/GET等其中一種

@apiDefine name [title] [description]
  定義一個註釋塊(不包含@api)，配合@apiUse使用能夠引入註釋塊
  在@apiDefine內部不可使用@apiUse
@apiUse name
  引入一個@apiDefine的註釋塊

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本相似，分別描述請求參數、頭部，響應錯誤和成功
  group表示參數的分組，type表示類型(不能有空格)，入參能夠定義默認值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法徹底一致，可是type表示的是example的語言類型
  example書寫成什麼樣就會解析成什麼樣，因此最好是書寫的時候注意格式化，(許多編輯器都有列模式，可使用列模式快速對代碼添加*號)

@apiPermission name
  name必須獨一無二，描述@api的訪問權限，如admin/anyone

 

示例:

定義一個200的返回結果

/** js
 * @apiDefine CODE_200
 * @apiSuccess (Reponse 200) {number} code 200
 * @apiSuccess (Reponse 200) {json} [data='""'] 若是有數據返回
 * @apiSuccessExample {json} Response 200 Example
 *   HTTP/1.1 200 OK
 *   {
 *     "code": 200,
 *     "data": ""
 *   }
 */

 

定義一個500的返回結果

/**
 * @apiDefine CODE_500
 * @apiSuccess (Response 500) {number} code 500
 * @apiSuccess (Response 500) {string} [message] error description
 * @apiSuccessExample {json} Response 500 Example
 *   HTTP/1.1 500 Internal Server Error
 *   {
 *     "code": 500
 *     "message": "xxx"
 *   }
 */

 

定義接口

/**
 * @apiDefine Data
 *
 * @apiParam (data) {string} [firstname]  Optional Firstname of the User.
 * @apiParam (data) {string} lastname     Mandatory Lastname.
 * @apiParam (data) {string} country="cn" Mandatory with default value "DE".
 * @apiParam (data) {number} [age=18]     Optional Age with default 18.
 */

/**
 * @api {POST GET} /api/test/hello[/:id] /api/test/hello[/:id]
 * @apiName test api
 * @apiGroup Hello World
 * @apiVersion 1.0.0
 * @apiDescription just a test
 * @apiPermission anyone
 * @apiSampleRequest http://test.github.com
 *
 * @apiParam {number} [id] any id
 * @apiParam {json} data object
 * @apiUse Data
 *
 * @apiParamExample {json} Request Example
 *   POST /api/test/hello/1
 *   {
 *     "data": {
 *       "firstname": "test",
 *       "lastname": "sails",
 *       "country": "cn"
 *     }
 *   }
 *
 * @apiUse CODE_200
 * @apiUse CODE_500
 */

 

最後生成文檔以後，結果以下所示

文／xun（簡書做者） 原文連接：http://www.jianshu.com/p/bb5a4f5e588a 著做權歸做者全部，轉載請聯繫做者得到受權，並標註「簡書做者」。