高质量api文档生成需五步：一、明确核心要素并规范提示词；二、提供结构化json元数据；三、嵌入真实代码片段锚定字段；四、分步验证输出；五、注入术语词典强制统一。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您使用DeepSeek生成API文档，但输出内容缺乏结构、准确性或可读性，则可能是由于提示词设计不当或未明确规范文档要素。以下是实现高质量API文档生成的具体步骤：
一、明确API文档的核心要素
DeepSeek作为大语言模型，需通过清晰指令识别API文档的必备组成部分，包括端点路径、请求方法、参数说明、请求示例、响应结构及错误码。缺失任一要素将导致文档不可用。
1、在提示词开头声明文档类型与目标读者，例如：“你是一名资深API技术写作者，为前端开发人员撰写RESTful接口文档。”
2、逐项列出必须包含的字段：接口名称、HTTP方法、完整URL路径、请求头要求、查询参数、请求体（JSON Schema格式）、成功响应示例（含HTTP状态码）、常见错误响应（含code和message字段）。
3、指定输出格式约束：“所有参数须标注是否必填，类型用括号注明（如string、integer、boolean）；响应字段需缩进展示层级关系。”
二、提供结构化输入模板
向DeepSeek输入标准化的API元数据，能显著提升文档一致性。模型无法自动推断未提供的字段，必须显式供给原始信息。
1、准备JSON格式的API描述，包含：{"endpoint":"/v1/users","method":"POST","description":"创建新用户","params":[{"name":"email","required":true,"type":"string","desc":"用户邮箱地址"}],"request_body":{"name":"string","age":"integer"},"responses":{"201":{"id":"string","created_at":"string"}}}
2、在提示词中要求模型严格基于该JSON生成文档，禁止虚构未声明的参数或状态码。
3、添加校验指令：“若JSON中未提供错误码定义，则响应部分仅保留‘201 Created’示例，不补充其他状态码。”
三、嵌入真实代码片段与上下文
纯文字描述易导致歧义，嵌入可运行的请求/响应片段能锚定模型对数据结构的理解，避免生成抽象或错误的字段名。
1、在提示词中插入curl命令示例：“curl -X POST https://api.example.com/v1/users -H 'Content-Type: application/json' -d '{"name":"Alice","email":"alice@example.com"}'”
2、附带对应的成功响应原始JSON：“{'id':'usr_abc123','name':'Alice','email':'alice@example.com','created_at':'2024-05-20T08:30:00Z'}”
3、要求模型从这些片段中提取字段名、类型和嵌套关系，并在文档中以相同命名呈现，字段名大小写与示例完全一致。
四、启用分步验证指令
单次生成易遗漏细节，通过分阶段指令可强制模型分层处理，确保每个模块符合技术文档规范。
1、第一阶段指令：“仅输出参数表格，表头为‘参数名｜是否必填｜类型｜说明’，按JSON中params数组顺序排列，无额外文字。”
2、第二阶段指令：“仅输出请求体JSON Schema，使用YAML格式，字段后紧跟冒号与类型注释，如‘name: string # 用户姓名’。”
3、第三阶段指令：“整合前两步结果，生成完整文档，标题为‘POST /v1/users’，各模块间空一行，不添加‘注意’‘提示’等主观表述。”
五、注入领域术语约束词典
API文档需统一术语，避免同义混用（如“user_id”与“userId”），模型需依赖显式词典消除歧义。
1、在提示词末尾附加术语对照表：“本文档中统一使用：用户标识符→user_id（全小写下划线）、时间戳→created_at（全小写下划线）、布尔值→true/false（不写作True/False）。”
2、加入强制替换规则：“生成过程中，若出现‘userId’、‘createdAt’、‘TRUE’等变体，必须立即替换为词典中指定形式。”
3、设置校验句式：“每段生成后，检查所有下划线字段是否符合词典，不符合则整段重写。”
