chatgpt生成的接口文档需经严格发布门槛校验：只保留已上线/联调/即将提测接口；错误码仅留日志真实触发的4xx/5xx；每个接口须配可执行curl、原始响应体、必填性标注及角色定制化参数说明；最终导出openapi yaml并验证编译通过。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
把ChatGPT生成的接口文档直接扔给前端或测试同学用，常出现字段漏标、示例缺失、错误码对不上、curl命令根本跑不通等问题——这不是文档没写完，是没过发布门槛。
先筛出真正要发布的接口
打开你刚让ChatGPT输出的文档草稿，逐条检查：只保留当前已上线、正在联调、或下周就要提测的接口。删掉所有“未来可能加”“预留扩展”“待确认字段”的条目。【未部署的接口写进文档，等于给协作方埋定时错误】。
对每个保留接口，确认其HTTP状态码是否真实触发过。翻最近3天的线上错误日志，只保留实际出现过的4xx/5xx码，比如日志里只有400和500，就删掉文档里写的401、404、503。
补全机器可执行的验证要素
第一步：在每个接口描述开头，粘贴一行可直接复制运行的curl命令。必须包含完整URL、全部必要Header（如Authorization、Content-Type）、-d参数值（JSON格式需缩进对齐，不要压成一行）。
第二步：紧接curl下方，贴出该请求对应的真实HTTP响应体。【必须是抓包工具（如Charles/Fiddler）截获的原始响应，不是ChatGPT编的、不是Postman模拟的、不是自己手写的】。删掉任何字段等于默认告诉别人“这个字段不重要”，但线上它存在且影响逻辑。
第三步：对每个请求参数，明确标注“必填/选填”，并在“示例”列填真实值而非占位符。比如password字段示例不能写“your_password”，而要写“Abc123!@#”，因为前端需要据此校验密码强度规则。
按角色重写字段说明
方法一：给前端看的参数说明，聚焦字段怎么传、什么格式、前端要不要做转换。例如：
register.x → “选填，整数，单位为像素，用于记录用户点击注册按钮时的横坐标；若不传，后端默认为0”。
方法二：给测试看的参数说明，聚焦边界值和异常路径。例如：
max_tokens → “必填，整数，取值范围1–4096；设为0返回400；设为4097返回400；传字符串‘100’返回400；传负数返回400”。
方法三：给第三方集成方看的说明，必须带协议约束。例如：
callback_url → “必填，字符串，必须为HTTPS协议，域名需提前在后台白名单备案，路径长度≤200字符，含查询参数总长≤512字符”。
导出为OpenAPI 3.0 YAML并验证
把ChatGPT生成的OpenAPI YAML内容复制进https://editor.swagger.io，等页面右上角出现绿色✅图标后再继续。
点击“Generate Server”→选择“spring-boot”，下载生成的zip包。解压后进入src/main/java目录，检查Controller类里每个方法上方是否都自动注入了@ApiParam、@ApiResponse等注解——【如果没有，说明YAML里paths定义有语法错误，退回上一步修正】。
用mvn clean compile执行编译。如果报错提示“cannot find symbol @ApiParam”，说明Swagger依赖版本与YAML结构不匹配，此时需降级到springfox-swagger2:2.9.2而非3.x。
