全局下载 apidoc

npm i -g apidoc

项目根目录配置 apidoc.json

{
    "name": "blog",
    "version": "1.0.0", 
    "description": "blog项目API文档", 
    "title": "blog API", 
    "url" : "http://localhost:3000", 
    "sampleUrl": "http://localhost:3000",
    "forceLanguage":"zh-cn",
    "template": {
      "withCompare": true,
      "withGenerator": true
    }
}

简单介绍下：

• name, version, description
  这三个配置项的内容会显示在生成文档的最上方，其中name即整个文档的大标题。

• title
  网页的标题，显示在浏览器标签上。

• url
  文档中每个API地址的前缀。

• sampleUrl
  当有此项时，每个API文档的最后会有Sample Request测试部分。该配置项是测试API地址的前缀。

• header, footer
  页面的头和尾。当多个页面都有相同的头和尾时，这个配置项就非常有用。子配置项中

  • title
    页面左边菜单栏中显示的标题。
  • filename
    指向页头或页尾的模板文件，apiDoc使用的是Markdown文件。

• template

  • withCompare
    生成的文档有版本比较功能。后面会介绍。默认为”true”。
  • withGenerator
    生成的文档页尾带有一段文字，表示这个文档是由apiDoc生成的，加上这个代表对作者的尊重吧。默认为”true”。

接口文件api注释

比如我的接口文件在 router/user.js

*/ 
/**
 * @api {get} /admin/user/reg 用户注册
 * @apiName reg
 * @apiGroup User
 *
 * @apiParam {String} us 用户账号
 * @apiParam {String} ps 用户密码.
 * @apiParam {Number} code 验证码.
 *
 * @apiSuccess {String} err Firstname of the User.
 * @apiSuccess {String} msg  Lastname of the User.
 * @apiSampleRequest http://localhost:3000/admin/user/reg
 * @apiVersion 1.0.0
 */

使用命令生成接口文档

apidoc -i router/ -o apidoc

如果 觉得太长可以配置

 "scripts": {
    "api":"apidoc -i router/ -o apidoc"
  },

使用

npm run api

效果

API文档注释

• @api {get} /users/:user_id Request User Information
  最主要的参数，{get}定义了HTTP请求是GET，API地址是/users/:user_id，文档中API的名称是Request User Information。

• @apiVersion 0.1.0
  API的版本号，默认显示在API名称的右方。该参数可用来在不同的版本之间做比较，后面会介绍。

• @apiName GetUser
  API名称，不影响文档。

• @apiGroup User
  API分组名，文档内容中和菜单栏中同一组的API会在一同显示，方便阅读。

• @apiPermission admin
  API的访问权限，文档中默认会API地址下面显示。没有权限要求的话，此项可以省略。

• @apiDescription API to get the user information.
  API的详细描述，默认显示在API名称的下方。

• @apiExample Example usage:
  API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:“。

• @apiParam {Number} user_id The user’s unique ID.
  API参数字段介绍，”{Number}“定义了字段类型，”user_id”是字段名称，后面则是字段描述。可以定义多个@apiParam字段。

• @apiSuccess {String} name Name of the User.
  API成功后返回的字段，如同@apiParam，”{String}“定义了字段类型，”name”是返回字段名称，后面则是字段描述。可以定义多个@apiSuccess字段。

• @apiSuccessExample {json} Success-Response:
  显示一个API成功返回后Response响应的示例，”{json}“代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiSuccessExample，默认在文档中会以标签形式列出，标签名就是”Success-Response:“。

• @apiError UserNotFound User was not found.
  API发生错误后的返回，”UserNotFound”是错误名称，后面则是错误描述。可以定义多个错误返回。

• @apiErrorExample {json} Error-Response:
  显示一个API错误返回后Response响应的示例，”{json}“代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiErrorExample，默认在文档中会以标签形式列出，标签名就是”Error-Response:“。

• @apiSampleRequest http://localhost:5000/users/:user_id
  文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除非这个API的测试URL比较特殊，需特别指定。