把 API 接口文档交给 AI 自动生成之后，我总结了三个它最容易凭空编造字段的坑

上个月我试了把后端代码直接丢给 AI，让它生成接口文档：请求参数、响应字段、错误码，一口气出。前几屏看着真专业，字段名、类型、示例值一应俱全。我差点就直接贴进内部 wiki 给前端同学用了。幸亏前端按文档调了一个"必填"参数，后端直接 500，才把这场乌龙拦下来。

坑一：它编字段。 代码里明明没有的字段，它为了"文档完整"自己加进去，还配上看起来合理的说明和示例。前端照着调，要么拿不到值，要么直接报错。最离谱的一次，它给一个查询接口造了个"totalCount"返回字段，实际接口根本不返回，前端拿去算分页，页面翻到第二页就空了。

坑二：它把可选和必填搞反。 我有个创建订单的接口，真正必填的只有订单号和用户 ID，其余都是可选。AI 生成文档时把五六个可选字段全标成了"必填（required）"。前端老老实实全传，结果有个字段后端没处理，传了反而触发校验异常。文档越写越像"全都要"，反而制造了 bug。

坑三：它抄旧版逻辑不更新。 接口半年前改过一次签名方式，代码里已经是新签名，但 AI 生成文档时参考了注释里一段没删干净的老描述，把旧签名写成了现行规则。对接的人按旧签名调，全部鉴权失败。代码注释里的历史信息，AI 是分不清"现在"和"曾经"的。

我现在只敢把 AI 当文档初稿机：它出完，我必须对着代码逐个接口核字段、核必填、核鉴权，核完才敢发。这个我建议先收藏，省得你像我一样险些把错误文档发到协作群。

我的判断：AI 写接口文档最大的风险不是写得丑，是写得"太像真的"。你们团队现在接口文档靠谁维护？是还在手写，还是已经交给 AI 初稿了？