Nest 使用 apidoc 生成接口文档

安装 apidoc

npm install apidoc -g

配置 apidoc

在项目根目录下创建 apidoc.json 文件，并添加以下内容：

• url 就是显示在接口地址前面的地址它会拼接接口路由前面

{
  "name": "XXX管理系统",
  "version": "0.0.0",
  "description": "接口文档描述",
  "output": "/docs", // 生成文档的目录
  "input": ["./src"], // 需要生成文档的目录
  "title": "接口文档",
  "url": "https://api.github.com/"
}

生成接口文档

在项目根目录下执行以下命令：

apidoc  -c ./apidoc.json --write-json

• 打包后 就会在项目的根目录下面生成一个 docs 的文件夹，里面就是生成的接口文档

• 找到 assets 目录下面有个 api-data.json

• 利用 apifox 导入这个 api-data.json 就可以了

vscode 插件

• 安装 ApiDoc Snippets 插件

• 使用快捷命令 输入 apidocument

• 然后 在生成的里面改即可

举例如下

// 先写同级，再写嵌套。需要嵌套的 利用字段名比如response.xx.xx表示嵌套
/**
 *
 * @api {POST} /testdemo/getcheckkeys 查到匹配的key
 * @apiName 查到匹配的key
 * @apiGroup testdemo
 * @apiVersion  0.0.0
 * @apiParam  {String} username 用户名
 * @apiBody  {String} value 对应的键
 * @apiSuccess {Object} response 响应数据
 * @apiSuccess {Number} response.code 200
 * @apiSuccess {Object[]} response.users 用户列表
 * @apiSuccess {Number} response.users.id 用户ID
 * @apiSuccess {String} response.users.username 用户名
 * @apiSuccess {String} response.users.email 邮箱
 * @apiSuccess {Object} response.users.profile 用户资料
 * @apiSuccess {String} response.users.profile.firstName 名
 * @apiSuccess {String} response.users.profile.lastName 姓
 * @apiSuccess {String} response.users.profile.avatar 头像URL
 * @apiSuccess {Object[]} response.users.roles 用户角色列表
 * @apiSuccess {Number} response.users.roles.id 角色ID
 * @apiSuccess {String} response.users.roles.name 角色名称
 * @apiSuccess {Date} response.users.createdAt 创建时间
 * @apiSuccess {Date} response.users.updatedAt 更新时间
 * @apiParamExample    {type} Request-Example:
 * {
 *     value : name
 * }
 *
 *
 * @apiSuccessExample {type} Success-Response:
 * {
 *     code : 200
 *     users : [
 *          id:10,
 *          username: 'admin',
 *         email: 'admin@example.com',
 *         profile: {
 *             firstName: 'John',
 *             lastName: 'Doe',
 *             avatar: 'https://example.com/avatar.jpg'
 *            },
 *         roles:[
 *            {
 *              id:10,
 *              name: 'admin',
 *            }
 *              ],
 *            createdAt:'2022-01-01 00:00:00',
 *            updatedAt:'2022-01-01 00:00:00'
 *
 *     ]
 * }
 *
 *
 */