apidoc.js生成API文档不显示required必填标识如何解决

1. 先检查接口参数注释的写法是否正确 #

apidoc的必填标识识别依赖参数注释的写法规范，和全局配置无关：

• 规则：@apiParam 注释中，字段名用[]包裹代表非必填，不加[]才是必填参数，只有被识别为必填的参数，才会渲染required标签。

正确写法示例：

/**
 * @api {post} /user/login 用户登录
 * @apiName Login
 * @apiGroup User
 *
 * @apiParam {String} mobile 手机号 // 无[]，为必填参数，会显示required标识
 * @apiParam {String} [verifyCode] 验证码 // 加[]，为非必填参数，不显示必填标识
 */

如果写注释时给所有参数都加了[]，哪怕打开showRequiredLabels配置，也不会出现任何必填标记。

2. 升级apidoc版本修复已知bug #

0.2.x全版本、以及部分早期0.3.x版本的apidoc存在模板配置读取bug，showRequiredLabels配置项不会被传入渲染层，执行以下命令升级到最新稳定版即可：

# 全局安装的apidoc执行
npm update apidoc -g

# 项目本地安装的apidoc执行
npm update apidoc --save-dev

升级后先删除之前生成的文档目录，重新执行生成命令，不要复用旧的静态文件缓存。

3. 确认配置文件被正确加载 #

如果执行apidoc命令时的工作目录不是apidoc.json所在的项目根目录，程序会读取默认配置（默认配置中showRequiredLabels为false），可以在执行生成命令时显式指定配置文件路径：

apidoc -c ./apidoc.json -i 你的接口代码目录 -o 文档输出目录

验证方式：修改apidoc.json里的name字段为特殊测试值，重新生成文档后看页头的项目名是否同步更新，就能确认配置是否生效。

4. 排查自定义模板兼容问题 #

如果你使用了第三方修改的自定义apidoc模板，部分模板会移除默认的必填标识渲染逻辑，这种情况可以临时去掉模板自定义配置，切回官方默认模板生成文档测试，如果默认模板下能正常显示必填标识，说明是自定义模板本身的代码问题，需要修改模板的参数渲染片段补上required标签的判断逻辑。

内容的提问来源于stack exchange，提问作者ARi