史上最全Apidoc文档生成详解

api接口文档生成（apidoc基本使用）

• 基本步骤

  1）. 安装apidoc （前提：在node环境下）

  npm i apidoc -g

  2）. 在项目的根目录配置 创建apidoc.json文件 并输入以下内容

  {
  “name”: “User”,
  “version”: “0.1.0”,
  “description”: “api文档”,
  “title”: “User”,
  “url”: “http://127.0.0.1:3000”
  }

  3）. 在项目的根目录创建 apidoc 文件夹

  4）. 注解 apidoc

  /**

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

  5）. 运行命令生成文档
  -i 代表文档注释来源（./routes） 只要在该目录下进行了注解的都能写入注释文档
  -o 代表生成注释文档目标路径（./apidoc）

  apidoc -i ./routes -o ./apidoc

• 页面详细解析

•   		apidoc.json详解
  

// {
//   "name": "用户管理", //1号区 页面大标题
//   "version": "0.1.0", // 2号区 页面大标题右侧
//   "description": "用户CRUD", //3号区 页面大标题下面的副标题
//   "title": "用户管理API",//0号区 网页的显示标题栏
//   "url" : "http://127.0.0.1:3000"//4号区 每一项请求的url固定写法
// }

•   	文档注解内容详解
  

/** 查询所有的用户的信息  方便自己查看，如果太多条API，可以折叠
 * @api {get}        /user              1.1 查询所有的用户的信息
//   （0）请求类型   （1）url路径前缀      （2）此API描述（3）标题导航
 * @apiName GetUser
//    这一项不会显示在页面上，但是不同的API这一项必须唯一
 * @apiGroup user
//    （4）（5）此API所属群组，同一群组的标题导航会放一起
 * @apiParam        {null}          null          null
//   所需传递的参数  （6）字段名     （7）字段类型    （8）描述
  * @apiSuccessExample {json} Success-Response:
//                      设置显示格式 
*  HTTP/1.1 200 OK
//   请求成功的结果示例（9）
 *     {
  "status": 0,
  "message": [
    {
      "id": 4,
      "name": "bb",
      "age": 12,
      "isdel": 0
    },
    {
      "id": 5,
      "name": "dd",
      "age": 16,
      "isdel": 0
    },
    {
      "id": 8,
      "name": "uu",
      "age": 11,
      "isdel": 0
    },
    {
      "id": 9,
      "name": "ss",
      "age": 12,
      "isdel": 0
    },
    {
      "id": 10,
      "name": "ff",
      "age": 16,
      "isdel": 0
    }
  ]
}
 */