Claude把接口返回示例写成字段说明提示词怎么让输出更适合发布

先明确一个常识：要让 Claude 输出的接口字段说明能直接用于开发者门户或对外技术文档，光有“内容正确”远远不够，还得在结构、语气、类型命名上完全匹配行业规范，不能留半点歧义。

先确认输出结构是否符合标准文档规范

打开 Claude 对话界面，敲提示词之前，**先检查你给它的示例返回体是否包含三类必需元素：字段名、类型、描述**。缺任何一类，生成的字段说明都会漏信息。比如只写 `{"code":0}` 却不说明 code 是整型、代表状态码，下游开发者拿到后根本无法安全解析。 把原始 JSON 响应复制进提示词时，务必用代码块包裹，并在上方加一句说明：“以下为真实接口返回体，请严格按字段名→类型→描述三级结构输出，不要添加额外解释。”

用结构化指令锁定输出格式

**方法一：用分隔符强制字段对齐** 在提示词末尾明确写：“请用竖线分隔字段名、类型、说明，每行一个字段，首行是表头：| 字段名 | 类型 | 说明 |”。这样做 Claude 会输出 Markdown 表格，直接粘贴进 Confluence 或 Swagger UI 的 Description 区域都没有问题。 **方法二：要求嵌套式 JSON Schema 风格** 输入：“请将以下返回体转换为 OpenAPI 3.0 兼容的 schema 片段，每个字段必须含 type、description，required 数组只列出必填字段。” 这样输出的结果能被 Postman、Apifox 等工具自动识别并渲染成交互式文档。 **【注意：如果原始返回里有嵌套对象（比如 data.user.name），Claude 可能会扁平化处理。必须在提示词中强调“保留原始嵌套层级，用点号表示路径”】**

过滤掉不适合发布的表述

**第一步**：禁止出现“示例值”“模拟数据”“仅供参考”等弱化语气词——这些词会削弱文档的权威性，开发者看到后难免怀疑字段是否真实存在。 **第二步**：替换口语化描述。比如把“这个字段就是用户昵称啦”改成“用户在平台设置的显示名称，最大长度32字符，支持中英文及常见符号”。 **第三步**：统一类型命名。要求 Claude 使用标准类型词：`string` / `integer` / `boolean` / `array` / `object`，不接受“字符串”“数字”“列表”等中文泛称。 直接在你提示词末尾加一句：“所有描述禁用‘例如’‘比如’‘一般’‘可能’等模糊限定词；类型名必须与 OpenAPI 3.0 规范完全一致。”