apidoc使用简单总结及例子

当前调试都是在apidoc@0.28.1版本下执行的，有不对的地方欢迎指出

安装apidoc

npm i apidoc --save-dev

配置apidoc

可以有以下三种形式存放配置

1. package.json

{
  "apidoc": {
    "name": "projectName",
    "url": "http://apiservice.com",
    "version": "1.0.0"
    // 此处省略更多apidoc配置
  }
}

2. apidoc.json

{
  "name": "projectName",
  "url": "http://apiservice.com",
  "version": "1.0.0"
  // 此处省略更多apidoc配置
}

3. apidoc.config.js

module.exports = {
  name: "projectName", // 形成的文档名称，如果没有配置，则从package.json中取对应字段
  version: "1.0.0", // 当前版本-默认显示的api版本，如果没有配置，则从package.json中取对应字段
  description: "project api doc description", // api文档描述，如果没有配置，则从package.json中取对应字段
  title: "api文档", // 形成的浏览器页面标题
  url: "http://apiservice.com", // api的前缀路径
  useHostUrlAsSampleUrl: false, // 使用hosturl当作测试api请求的url前缀 - 经测试感觉无效
  sampleUrl: 'http://apiTest.com', // 页面测试api请求的url前缀，会覆盖useHostUrlAsSampleUrl - 这个配置项不设置的话，内部的@apiSampleRequest设置也不起作用
  // 头部和尾部文档配置
  header: {
    title: "headerMenu", // 标题-用于形成左侧菜单名称
    filename: "header.md", // 文档内容
  },
  footer: {
    title: "footerMenu", // 标题-用于形成左侧菜单名称
    filename: "footer.md", // 文档内容
  },
  // api-name排序或者group-name排序, 先进行group排序-再进行name排序, 没有的则自动在后面显示
  order: [
    "login",
    "save",
    "User",
    "Menu"
  ],
  template: {
    forceLanguage: 'zh_cn', // 生成apidoc的默认语言，默认zh_cn（中文简体）
  	withCompare: true, // 是否需要进行版本对比，默认true
  	withGenerator: true, // 是否需要显示编译信息（主要是编译日期和apidoc版本），默认true
    jQueryAjaxSetup: { // 默认的jquery的ajax的配置
      headers: {
        token: '123'
      }
    },
    aloneDisplay: true, // 是否需要单独显示某个api，默认fale
  }
}

生成apidoc

apidoc -i app/routes/ -o app/public/apidoc/

其中app/routes/是需要解析的目录，app/public/apidoc/是生成的apidoc文档输出目录

apidoc编写的param

• @apiIgnore [msg] 生成文档时忽略该api

/**
 * @apiIgnore not finish
 * @api {get} /user/login 用户登录
 * 生成文档中不会包含此请求的信息
*/

• @apiPermission name 说明api权限

/**
 * @api {get} /user/login 用户登录
 * @apiPermission admin
 * 表明admin权限的才可以测试此请求
*/

• @api {type} path [title] 定义api路径，以及形成左侧菜单的名称

/**
 * @api {get} /user/login 用户登录
 * 此请求方式为 get
 * 请求路径为 /user/login
 * 生成文档中的左侧菜单为 用户登录
*/

• @apiDescription text 定义api描述信息

// 描述信息可以多行，生成文档如果想要换行显示，则注释需要间隔一行才行
/**
 * @api {get} /user/login 用户登录
 * @apiDescription 此api用于用户登录
 * 所有用户都可以登录
 * 
 * 但是需要先用手机号注册才行
*/

• @apiGroup name 定义api分组名称

/**
 * @api {get} /user/login 用户登录
 * @apiGroup User
*/

• @apiName name 定义api名称

// 此处api名称为login，用于文档生成的定位api的表示
/**
 * @api {get} /user/login 用户登录
 * @apiName login
*/

• @apiParam [(group)] [{type}] [field=defaultValue] [description] 定义参数-可以分组

/**
 * @apiParam {String="1-管理员","0-普通用户} type=1 用户类型
 * @apiParam {String} [userName] 用户名
 * 
 * @apiParam (address) {String} [city] 城市
 * @apiParam (address) {String} [street] 街道
*/

• @apiParamExample [{type}] [title] example 定义param的示例

/**
 * @apiParamExample {json} Request-Example:
 * {
 *    "name": "首页", // 菜单名称
 *    "path": "/home", // 菜单路径
 *    "icon": "home", // 菜单图标-可为空
 *    "level": 1, // 菜单层级
 *    "parentCode": "0" // 父级菜单编码
 * }
*/

• @apiBody [{type}] [field=defaultValue] [description] 定义body参数 用法同@apiParam

• @apiError [(group)] [{type}] field [description] 定义error信息 用法同@apiParam

• @apiErrorExample [{type}] [title] example 定义Error的示例 用法同@apiParamExample

• @apiHeader [{type}] [field=defaultValue] [description] 定义header 用法同@apiParam

• @apiHeaderExample [{type}] [title] example 定义Header的示例 用法同@apiParamExample

• @apiSuccess [(group)] [{type}] field [description] 定义返回的数据 用法同@apiParam

• @apiSuccessExample [{type}] [title] example 定义返回的数据的示例 用法同@apiParamExample

• @apiDefine name 定义块 name-块名称

• @apiUse name 使用定义的块 name-块名称

• @apiVersion version 定义api版本 version-版本号

• @apiSampleRequest url 调整示例请求的url

// 经测试，此设置需要在apidoc.config.js中配置sampleUrl才生效
// eg: sampleUrl = http://api.com;

/**
 * @api {get} /user/login 用户登录
 * @apiSampleRequest off
 * 此时会关闭-发送示例请求
*/

/**
 * @api {get} /user/login 用户登录
 * @apiSampleRequest http://apii.com
 * 发送示例请求的url为 http://apii.com
*/

/**
 * @api {get} /user/login 用户登录
 * @apiSampleRequest http://apii.com/api/login
 * 发送示例请求的url为 http://apii.com/api/login
*/

/**
 * @api {get} /user/login 用户登录
 * @apiSampleRequest /api/login
 * 发送示例请求的url为 http://api.com/api/login
*/

• @apiExample [{type}] title example api使用示例

• @apiDeprecated text 弃用

/**
 * @apiDeprecated use now (#Group:Name).
*/

• @apiPrivate 是否私有的-经测试无效

// 配合行内命令 --private false|true 使用

几个例子

• GET /user/list

• POST /user/login

• GET /menu/tree

demo地址

https://gitee.com/baoyinYang/apidoc-demo