apiDoc

全局安装，方便用命令创建文档

1
npm install apidoc -g

配置

在你的项目根目录下新建apidoc.json文件，该文件描述了项目对外提供接口的概要信息如名称、版本、描述、文档打开时浏览器显示标题和接口缺省访问地址。
apidoc.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "name": "xxx Api", 
    "version": "1.0.0", 
    "description": "xxx Api Documentation", 
    "title": "xxx",  
    "url" : "http://域名/api/v1",
    "sampleUrl": "http://域名/api/v1",

    "template": {
      "withCompare": true,
      "withGenerator": true,
      "forceLanguage":"en"
    },
  //顺序、若有需要可配置(books, student,xxx) Resources Name
  "order": ["xxx","xxx"]
}

Sample

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
/**
 * Get Access Token
 * @api {POST} /token GetAccessToken
 * @apiDescription Generate a token that can be passed with each API request.
 * @apiName GetAccessToken
 * @apiPermission API User
 * @apiParam (Parameters) {String} username username
 * @apiParam (Parameters) {String} password password
 * @apiParamExample {json} Sample (Request body formats: text/plain, application/x-www-form-urlencoded, text/json, application/json)  :
 * {
 *   "username": "your accont",
 *   "password": "your password"
 * }
 * @apiSampleRequest off
 * @apiSuccessExample {json} Response (Response body formats: application/json, text/json):
 * Success Response :
 * Status: 200 OK
 * {
 *   "status": "success",
 *   "message": "Authentication successful.",
 *   "data": {
 *      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikpxxxxx.xxxxx2VybmFtZSI6InNsIiwiaWF0IjoxNTQ1MTkyMzY4LCJleHAiOjE1NDUxOTI4NDh9.xxxxxxgS1Yw8rNRD31p97A7fdWvmkrXxo3llMJowX7U"
 *   }
 * }
 * Or 
 * Bad Response:
 * Status: 400 
 * { 
 *   "status": "failure", 
 *   "message": "Authentication failed. Please provide a correct username or password."
 * } 
 * @apiGroup Token
 * @apiVersion 1.0.0
 */

生成

文档初始化或发生改变时，在应用程序根目录执行相应命令
以此项目为例：

apidoc -i api/v1 -o public/apiDoc

1
2
3
4
-i input
-o output

指定文件夹路径

具体注释写法参照官网解释：
http://apidocjs.com/#run

public/apiDoc内文件不用上传到代码管理中
可直接执行npm run doc命令自动生成