原文地址：RESTful web API文档生成器

问：开发业务模块代码最重要的是什么？
答：API接口文档

如果你是后台开发，是否会有以下困扰：

• 开发API接口，还要通过wiki写接口文档，严重影响效率
• 接口不是一次就能定下来的，后续可能还要维护，所以还需要去修改文档

如果你是前端工程师，是否有过下面的困扰：

• 返回的数据怎么少字段，后台什么时候改了接口

我们总是吐槽文档不全，文档写的不好，然而却没有想到开发的同时顺便把文档也写了。这篇博文的重点就是为大家介绍一款生成RESTful web API文档的神器——apidoc，GitHub 4000多star。这款神器通过源代码中的注释生成最终的文档，所以需要按照规范编写注释。

安装和使用

前言

文中的例子全部使用Javadoc-Style编写，也可以在所有支持Javadoc的语言（如C#, Go, Dart, Java, JavaScript, PHP, TypeScript等）中使用。其他语言可以使用它们特定的多行注释。

/**
 * This is a comment.
 */

安装

npm install apidoc -g

使用

apidoc -i myapp/ -o apidoc/ -t mytemplate/

使用mytemplate/下的模板文件，为myapp/目录下的所有文件创建api文档，并保存在apidoc/目录下。如果不带任何参数，apiDoc为当前目录以及子目录下的所有.cs, .dart, .erl, .go, .java, .js, .php, .py, .rb, .ts文件创建文档，并保存在./doc/目录。

命令行参数

# 查看命令行参数
apidoc -h

列出部分重要参数：

Grunt模块

作者也为大家开发了一款grunt的打包工具http://github.com/apidoc/grunt-apidoc。

npm install grunt-apidoc --save-dev

模板

apiDoc默认模板：使用了handlebars，Bootstrap，RequireJS和jQuery为输出的api_data.js和api_project.js文件生成html页面。

apiDoc默认使用一个复杂的模板，支持如下功能：

• 版本管理：查看不同版本的API
• 比较：查看一个API的两个版本之间的区别

你也可以使用自己创建的模板，为apiDoc生成的文件api_data.js, api_project.js或者json格式的文件api_data.json, api_project.json。

模板源代码：https://github.com/apidoc/apidoc/tree/master/template

扩展

apiDoc也可以扩展自己的参数，具体细节请查看apidoc/apidoc-core项目的lib/parsers/, lib/workers/目录。

配置

apiDoc提供了两种配置方式，要么在工程根目录添加apidoc.json文件，要么在package.json中添加apidoc字段。

apidoc.json

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

package.json

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

apidoc.json配置字段

apiDoc默认模板特定的配置字段

Header/Footer

在apidoc.json添加header和footer。

{
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  }
}

示例

继承

你可以将文档中多次使用的部分放到一个定义中。如下：

/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/**
 * @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"
 *     }
 *
 * @apiUse UserNotFoundError
 */

/**
 * @api {put} /user/ Modify User information
 * @apiName PutUser
 * @apiGroup User
 *
 * @apiParam {Number} id          Users unique ID.
 * @apiParam {String} [firstname] Firstname of the User.
 * @apiParam {String} [lastname]  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *
 * @apiUse UserNotFoundError
 */

继承只能包含一层，多层级将会降低行内代码的可读性，增加复杂度。

版本控制

保存之前定义的文档块，用于不同版本的接口比较，因此前端开发很容易看到哪些地方有变化。

在修改接口文档之前，将历史文档块复制到文件_apidoc.js。

所以在每个文档块设置@apiVersion非常重要。

apiDoc参数

结构体参数@apiDefine用于将文档块定义为可复用的整体，并且可以包含在api文档块中。

除了其它定义块，一个定义的块中可以包含所有的参数（如@apiParam）。

@api

必须包含这个标记，否则apiDoc将会忽略文档块。定义块@apiDefine不需要@api。

@api {method} path [title]

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

@apiDefine

定义一个通用块或者权限块，每个块中只能有一个@apiDefine，使用@apiUse导入通用块。

@apiDefine name [title]
    [description]

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

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

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

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

@apiDeprecated

标记废弃的API

@apiDeprecated [text]

/**
 * @apiDeprecated */

/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiDescription

API的详细描述

@apiDescription text

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

@apiError

返回的错误参数

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

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

@apiErrorExample

返回的错误示例，输出为格式化的代码

@apiErrorExample [{type}] [title]
    example

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

@apiExample

API的使用示例，输出为格式化的代码

@apiExample [{type}] title
    example

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

@apiGroup

应该一直使用，定义API文档块所属的分组。分组用于生成输出中的主导航，结构定义不需要@apiGroup

@apiGroup name

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

@apiHeader

描述传递给API的请求头，类似@apiParam，只不过输出文档在参数之上。

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

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

@apiHeaderExample

请求头参数示例

@apiHeaderExample [{type}] [title]
    example

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

@apiIgnore

@apiIgnore块不会被解析，如果你在源代码中留下过期或者未完成的api，并且不想将其发布到文档中，这个标识符非常有用。

将其放在块的顶部

@apiIgnore [hint]

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

@apiName

应该永远使用，定义API文档块的名称，名称将用于生成输出文档中的子导航。结构定义不需要@apiName

@apiName name

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

@apiParam

定义传递给API的参数

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

/**
 * @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

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

@apiPermission

权限名称，如果用@apiDefine定义名称，生成的文档将会包含额外的名称和描述

@apiPermission name

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

@apiSampleRequest

此参数配合apidoc.json配置中的sampleUrl参数使用，如果配置了sampleUrl，所有API方法都将有api测试表单，并追加在@api结束位置。如果未配置sampleUrl，仅包含@apiSampleRequest的方法有测试表单。
如果在方法块中配置了@apiSampleRequest url，这个url作为请求地址（当它以http开头，会覆盖sampleUrl）
如果配置了sampleUrl，并且想在指定方法不包含测试表单，可以在文档块中配置@apiSampleRequest off。

@apiSampleRequest url

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

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

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

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

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

@apiSuccess

成功返回的参数

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

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

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

// 带对象示例
/**
 * @api {get} /user/:id
 * @apiSuccess {Boolean} active Specify if the account is active.
 * @apiSuccess {Object} profile User profile information.
 * @apiSuccess {Number} profile.age Users age.
 * @apiSuccess {String} profile.image Avatar-Image.
 */

// 带数组示例
/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles List of user profiles.
 * @apiSuccess {Number} profiles.age Users age.
 * @apiSuccess {String} profiles.image Avatar-Image.
 */

@apiSuccessExample

成功响应的信息，按格式化代码输出

@apiSuccessExample [{type}] [title]
    example

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

@apiUse

包含一个@apiDefine定义的块。如果与@apiVersion一起使用，将包含相同的或最近的一个

@apiUse name

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

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

@apiVersion

配置文档块的版本，也可以在@apiDefine中使用，具有相同组和名称的API，可以在生成的文档中比较不同的版本，因此你或前端开发人员可以回溯自上一个版本以来API中的更改

@apiVersion version

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

到此为止，你应该对apidoc熟悉了一大半了吧！其实作为开发者，一定要养成写注释、写文档的习惯，也是程序员进阶的必要条件。

谨以此文鞭策自己。