claude生成openapi文档需严格约束：明确角色为api文档工程师，输入必须是带注解的结构化代码，强制yaml格式且不补全未声明字段；用模板锚点和反例约束确保字段顺序、命名及状态码描述准确；禁止幻觉补全，最后校验规范一致性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
用Claude生成接口文档时，提示词必须明确告诉模型要输出什么格式、字段含义和约束条件，否则它会自由发挥，把请求参数写成散文，把状态码解释成故事。
基础结构：先定义角色和任务
第一步：在提示词开头直接指定Claude的身份和本次输出目标。不要写“你是一个AI助手”，要写“你是一名资深后端API文档工程师，正在为内部微服务编写OpenAPI 3.0风格的接口说明”。
第二步：紧接着给出原始输入材料——必须是结构化内容。例如：“以下是一个Spring Boot Controller方法的源码片段，请基于此生成文档”，然后粘贴带@RequestMapping、@RequestBody、@PathVariable等注解的真实代码块。不能只给模糊描述如“有个登录接口”。
第三步：强制限定输出范围。写明“只输出YAML格式的OpenAPI 3.0 spec，不加任何解释性文字、不补全缺失字段、不猜测未声明的参数”。【未声明的参数绝不自行添加，否则会导致前端调用时400报错】
字段级控制：让每个字段都可预期
方法一：用模板锚点法
在提示词中插入占位符式结构，例如：“请严格按以下字段顺序和命名输出：paths → /user/login → post → summary（一句话功能描述）→ description（业务上下文，不超过2行）→ requestBody → content → application/json → schema → $ref → #/components/schemas/LoginRequest”。这样Claude不会把summary写成description，也不会把schema嵌套错层。
方法二：反例约束法
直接列出禁止行为：“不使用‘可能’‘通常’‘建议’等模糊词；不将@NotNull注解解释为‘最好传’；不把HttpStatus.OK写成‘表示成功’而必须写‘200: 操作成功，返回UserDTO对象’”。
错误拦截：提前堵住常见幻觉
在提示词末尾加一句硬性规则：“若代码中未出现@ApiResponse注解，则components → responses部分留空，不补默认200响应；若方法无@RequestBody，则requestBody字段整体删除，不写‘无请求体’之类说明”。【Claude默认会补全缺失块，这会导致Swagger UI渲染出根本不存在的参数】
最后追加校验指令：“输出完成后，逐行检查是否所有字段名与OpenAPI 3.0官方规范完全一致，特别是required数组必须是字符串列表，不是布尔值或对象”。
