如何在apidoc中定义apiParam类型的JSON对象参数

apidoc 原生支持对象类型参数的结构化展示，不需要引入额外插件，核心是用点路径语法声明对象下的子属性即可。

针对你给出的data对象，标准注释写法如下：

/**
 * @api {POST} /your/interface/path 对应接口的路径和名称
 * @apiName YourInterfaceName
 * @apiGroup 接口所属分组
 *
 * @apiParam {Object} data 业务提交参数对象
 * @apiParam {null|Number} data.id 数据唯一ID
 * @apiParam {null|Number} data.status 数据状态标识
 * @apiParam {null|String} data.category 数据分类值
 */

配置说明 #

• 必须先单独声明父级对象本身，类型指定为Object，补充对象的用途说明
• 对象下的所有子属性，统一用父对象名.属性名的格式逐行声明，和普通平级参数的写法规则完全一致，apidoc生成文档时会自动将这些子属性归集到父对象的结构树中
• 如果要匹配你示例里所有字段初始值为null、允许传空的特性，可以直接用可选参数+默认值的写法简化，比如字段行可以写成：

  @apiParam {Number} [data.id=null] 数据唯一ID
  

  外层方括号代表该参数非必填，等号后标注默认值为null，生成的文档会自动展示这个默认值规则
• 多层嵌套对象也可以用同样的规则延伸，比如存在data.user.avatar这类三级属性，直接逐行写路径即可，不需要额外做层级标记

内容的提问来源于stack exchange，提问作者Fatih Doğan