简介这份PDF聚焦如何借助DeepSeek自动生成API文档与开发者指南适合需要提升技术文档编写效率的软件工程师、技术负责人及AI工具使用者。内容从技术文档现状与挑战出发系统梳理DeepSeek核心原理、代码解析与自然语言生成机制再到环境准备、项目导入、参数设置、文档生成、审核优化等完整流程并通过实际案例比较使用前后的改进效果同时与Swagger、Sphinx等同类工具展开功能与用户体验对比归纳准确性、兼容性、性能等典型问题及对策有助于在实际项目中落地应用。文档共24页覆盖原理、实践、案例与展望目录结构清晰原理到实战完整。资源包内仅1个PDF文件大小约1.93MB查阅便捷目前已有83人学习下载适合希望通过AI辅助工具改造文档工作流、降低维护成本的开发者参考。1. 技术文档降维打击让 DeepSeek 自动生成 API 文档与开发者指南你刚把 SDK 重构完接口改了 12 处文档还停在三个月前打开旧版 API 文档发现连认证流程都是错的——这种时候 DeepSeek 自动生成 API 文档与开发者指南这整套方案解决的不只是「写文档累」而是「文档永远跟不上代码」这个工程债务。它的核心做法很直接把代码仓库里的 OpenAPI 描述、函数签名、调用示例喂给 DeepSeek让它按你给的骨架输出结构化的 Markdown再统一合成 PDF。适合手里维护着十个以上接口、却没有专职文档工程师的团队也适合把「写文档」当成 API 平台交付物一部分的后端开发者。我下面讲的每条命令和参数都是按这条路子跑过、也踩过坑的版本。2. 为什么选 DeepSeek 做文档生成先搞清「抽取」和「创作」的边界2.1 DeepSeek 在这类任务里的卡位不是聊天是结构还原做 API 文档生成最容易翻车的不是模型不会写而是模型太会写——你让它描述一个「获取用户列表」的接口它给你补出八个不存在的查询参数还配上错误码。这是因为通用模型在生成任务里默认开启「补充细节」模式而 API 文档恰恰要求「只改写、不新增」。DeepSeek 在指令跟随上的表现让「约束它不要自由发挥」这件事从玄学变成了可配置项。我的选型对比通常只看三个维度指令跟随的稳定性、中文表达的自然度、以及结构化输出JSON/Markdown的可解析性。相比之下有些模型英文文档很漂亮但中文接口说明总带着翻译腔另一些模型对话体验好但连续生成 4000 token 后表格就开始错位。DeepSeek 的上下文窗口最大能到 1M token这意味着你可以把一整份 OpenAPI JSON 原文塞进去而不是像我最初那样把代码仓库几千个文件全部丢给模型——后者会直接触发 400 错误。1M 不是给你胡乱塞东西的许可证它真正的好处是一份中等规模的 API 定义几百个 path可以整段进入上下文模型能看到接口之间的关联而不是切碎了逐条瞎猜。还有一个常被忽略的点DeepSeek 的 API 兼容 OpenAI 的调用格式你在本地开发环境里用openai这个 Python SDK只改base_url和api_key其余代码一字不动。这意味着团队里已有的 LLM 工具链可以零成本切换。如果是纯内网环境也可以用 vLLM 把开源权重部署起来SDK 调用方式不变只是base_url指向内网地址。2.2 三段式管线预检、生成、排版各干各的活很多文档自动化项目死在第一步试图让大模型直接读源码生成文档。我试过把项目根目录整个交给 DeepSeek结果有三类问题源码文件占满上下文导致关键接口信息被挤掉模型把私有方法的逻辑当成公开 API 写进文档更糟的是它会「理解」代码后自行总结接口语义而不是基于真实的接口签名来写——生成的文档看着通顺拿去对接直接报 404。所以我现在把整个过程拆成三段各用各的工具预检信息抽取用 FastAPI 自带的 OpenAPI 生成、Spring Doc、或者 apibuilder 这类工具把代码里的路由、参数、返回结构固化成openapi.json。这一步不经过任何模型保证信息源是「代码事实」而不是「模型理解」。生成LLM 改写把精简过的 OpenAPI 片段 写作规范 prompt 交给 DeepSeek让它产出 Markdown。这里的核心约束是模型只能基于给定的 JSON 做复述和解释不能新增字段。排版文档合成把 DeepSeek 生成的多个 Markdown 文件用 pandoc 合并成 PDF统一目录、页眉和代码样式。这个拆分不是为了炫技而是为了出问题时能定位。预检环节出错是工具配置问题生成环节出错是 prompt 或参数问题排版出错是样式问题。三段各自独立可重跑不会互相污染。2.3 写作规范先行prompt 是唯一的生产资料在写任何调用代码之前先把写作规范固化成一个 system prompt。我参考中文技术文档写作规范里的约定动词开头、每段只说一件事、参数说明必须给类型和取值范围、代码示例必须带注释。这些规则直接写进 prompt而不是期望模型「懂规矩」。下面是我常用的 system prompt 模板SYSTEM_PROMPT 你是一名资深 API 文档工程师。你的任务是基于给定的 OpenAPI 片段生成中文接口文档。 写作规范必须遵守 1. 只描述输入 JSON 中真实存在的字段禁止补充、推断或根据常识添加任何参数。 2. 每个参数必须包含参数名、类型、是否必填、取值范围、默认值如有、含义。 3. 响应示例必须和输入 JSON 中的 schema 完全一致可以简化嵌套层级但不能改字段名。 4. 用中文写作动词开头如获取用户列表创建订单每段不超过 5 行。 5. 禁止使用等等可能大概这类模糊词。 6. 输出格式为 Markdown标题层级从 ### 开始。 输入数据格式 - 接口路径、方法、请求参数、响应结构均来自 OpenAPI JSON 原文。 - 若 OpenAPI 片段为空直接输出无可用信息不编造。 这段 prompt 里最重要的不是前五条规范而是第六条和「若 OpenAPI 片段为空」这句话——它把模型的自由度压到最低。没有这条兜底模型遇到缺失信息就会自动脑补后续你在文档里看到不存在的字段时根本分不清是代码问题还是文档问题。调用时的参数我一般固定在temperature0.2偏低保证确定性、max_tokens3000防止单次输出过长截断、top_p0.5。这些参数不是玄学后面我会讲到它们各自卡住了哪些典型故障。3. 用 DeepSeek 自动生成 API 文档从 openapi.json 到可发布 Markdown3.1 预检先把代码固化成 OpenAPI 描述文件无论你用什么语言写后端第一件事永远是拿到一份忠实描述接口的 OpenAPI JSON。以 FastAPI 为例框架会帮你自动生成并挂在/openapi.json路由上但这份文件通常包含大量components.schemas定义直接喂给模型会浪费 token 且容易超出上下文限制。我一般会先跑一个精简脚本只保留生成文档真正需要的字段import json def compact_openapi(src_path: str, dst_path: str): 压缩 OpenAPI 描述去掉无用的扩展字段保留 paths 和精简后的 schemas with open(src_path, r, encodingutf-8) as f: spec json.load(f) # 保留接口定义主体剔除 swagger 扩展信息 compact { openapi: spec.get(openapi, 3.0.0), info: spec.get(info, {}), paths: spec.get(paths, {}), components: {schemas: spec.get(components, {}).get(schemas, {})} } with open(dst_path, w, encodingutf-8) as f: json.dump(compact, f, ensure_asciiFalse, indent2) # 统计接口数量与 schema 数量作为后续分批的参考 print(fpaths: {len(compact[paths])}) print(fschemas: {len(compact[components][schemas])}) # 用法示例读取 fastapi 生成的 openapi.json输出精简版 compact_openapi(openapi_raw.json, openapi_compact.json)这段脚本的作用是把原始 OpenAPI 文件里的冗余扩展字段比如x-openapi-router-controller、x-codegen-request-body-name这一类框架注入信息剥掉。保留info是因为文档头部需要版本号和描述保留paths是因为接口路径和 HTTP 方法是文档的核心骨架保留components.schemas是因为响应结构定义要从这里引用。跑完脚本后打印的 path 数量直接决定你下一步怎么分批调用 DeepSeek——我的经验是每批 5 到 8 个 path 最合适太少浪费请求次数太多则单次响应容易超时或截断。如果你维护的是老项目没有现成的/openapi.json常见做法是引入 SpringDocJava、Swagger 注解Node.js、或者用 apibuilder 从路由代码反向生成。这一步别指望模型替你完成原因前面说过模型读源码生成的接口定义本质是「推断」而文档需要的是「事实」。预检环节宁可多花一小时把工具配好也不要省这个功夫让模型编。3.2 核心生成脚本DeepSeek API 调用的最小可跑通版本拿到精简后的 OpenAPI 文件下一步就是写生成脚本。这里我直接用openaiSDK通过base_url指向 DeepSeek 的 API 端点。完整代码如下关键位置都加了注释import json import time from openai import OpenAI # DeepSeek API 兼容 OpenAI 格式仅需替换 base_url 与 api_key client OpenAI( api_keysk-你的密钥, # 从 DeepSeek 开放平台获取不要在代码里硬编码 base_urlhttps://api.deepseek.com/v1 # 注意是 /v1 结尾 ) SYSTEM_PROMPT 这里粘贴上一节的完整 system prompt def generate_api_doc(path_block: dict) - str: 输入一个包含多个 path 的字典输出该批接口的 Markdown 文档 block_json json.dumps(path_block, ensure_asciiFalse, indent2) response client.chat.completions.create( modeldeepseek-chat, # 通用对话模型文本生成任务选这个 messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f请基于以下 OpenAPI 片段生成接口文档\n{block_json}} ], temperature0.2, # 偏低温度减少自由发挥 max_tokens3000, # 限制单次输出长度 top_p0.5, # 核采样配合低温度进一步压稳 streamFalse # 关闭流式便于直接拿到完整结果 ) return response.choices[0].message.content # 分批处理每 6 个 path 一批累计结果 def batch_generate(compact_path: str, output_path: str, batch_size: int 6): with open(compact_path, r, encodingutf-8) as f: spec json.load(f) paths spec[paths] path_items list(paths.items()) doc_sections [f# {spec[info].get(title, API Reference)}\n] for i in range(0, len(path_items), batch_size): batch dict(path_items[i:i batch_size]) print(f正在生成第 {i // batch_size 1} 批 f共 {len(batch)} 个接口{i}~{i len(batch)}) for attempt in range(3): # 失败重试最多 3 次 try: markdown generate_api_doc(batch) doc_sections.append(markdown) break except Exception as e: print(f第 {attempt 1} 次调用失败{e}) time.sleep(2) # 退避 2 秒再重试 else: print(f批次 {i // batch_size 1} 连续 3 次失败跳过) with open(output_path, w, encodingutf-8) as f: f.write(\n\n.join(doc_sections)) print(f文档已写入{output_path}) if __name__ __main__: batch_generate(openapi_compact.json, api_docs.md)这段代码遵循一个原则api_key不该硬编码在源码里。你可以通过环境变量DEEPSEEK_API_KEY读取这样至少不会把密钥提交进 git。其次batch_generate里的time.sleep(2)不是多余的——DeepSeek API 在持续高并发下偶发 429 限流短退避比立刻重试成功率高得多。至于max_tokens3000我特意限制单次输出长度因为它直接关系到下一个坑如果模型输出被截断你拿到的是一段以半个 JSON 结尾的碎文档而这在max_tokens设得过大时反而不容易察觉。调用完成后你会得到一个api_docs.md里面是按批次生成的接口说明。max_tokens的设定比你以为的更重要设得太小长接口的响应示例会被切半设得太大比如 8000一旦模型开始重复输出浪费的 token 会让账单难看而且超长输出的稳定性反而下降。3.3 参数设置与成本控制api 调用量和价格都藏在细节里DeepSeek 按 token 计费文档生成这种任务的特点是「输入大、输出可控」。我见过有人把未精简的原始 OpenAPI 直接喂进去一个接口带五个嵌套的 schema每次调用重复传相同的components.schemasapi 调用量直接翻三倍。常见做法是预检时把每个接口要用的 schema 引用提前解析出来拼到对应的 path 块里而不是整份 schemas 一起塞。另一个控制成本的参数是top_p。在文档生成场景里top_p0.5配合temperature0.2比单独把温度调到 0 的效果更稳——因为温度归零会让模型在长文本里陷入重复循环而核采样限制的是候选词集合两者精细配合后输出质量既稳定又不呆板。下面的表格是我在几次迭代后固定的推荐参数参数推荐值作用调低/调高的后果temperature0.2控制随机性调至 0 易重复高于 0.5 开始出现编造字段top_p0.5限制候选词集合调高到 0.9 后输出多样性提升但结构稳定性下降max_tokens3000限制单次输出长度过小截断过大遇到重复输出时浪费计费batch_size5~8 path/批控制单次输入规模过小请求次数多过大单次响应时间变长还有一条经验同一个 system prompt 在连续多次请求时DeepSeek 会命中上下文缓存这部分 token 计费有折扣。所以你在循环里应该把SYSTEM_PROMPT保持字符串完全一致不要因为代码格式化而把换行或空格改掉——缓存是按前缀精确匹配的任何字符差异都会导致缓存失效重新计费。4. 从 API 文档到开发者指南结构编排与 PDF 落地4.1 两种文档两种受众API Reference 不等于开发者指南很多团队把 API 文档和开发者指南混为一谈生成一份文档就想两边复用。实际上这就像拿 CMOS sensor 的技术手册去教硬件工程师做调试——信息都在但排布方式完全不对。API 文档解决的是「某个接口怎么调」它的颗粒度是单个 path开发者指南解决的是「一个完整流程怎么走通」它的颗粒度是「认证 → 第一次请求 → 分页 → 错误处理」。DeepSeek 在生成这两类文档时需要完全不同的 prompt 和完全不同的结构化约束。维度API 文档开发者指南读者对接第三方系统的工程师刚接触平台的新手开发者核心问题这个接口的参数和返回是什么我怎么用这套 API 完成一个真实功能起点数据OpenAPI JSON 的 paths 片段一组典型业务场景的描述输出结构按 path 分节按「快速开始→认证→核心流程→错误排查」分章模型自由度低只能复述给定 JSON中可补充流程性描述我的做法是分两阶段生成先用 DeepSeek 从 API 文档里提炼出「典型调用链」再基于调用链生成开发者指南。这样可以避免模型在写指南时凭空发明接口——凡是指南里出现的示例代码都必须在 API 文档里能找到对应的接口定义。这条约束写进 prompt后续可以拿脚本自动校验。4.2 编排生成指南先给骨架再填肉开发者指南如果一次性让模型生成整篇文章往往会出现「开头详细、结尾潦草」的问题因为长文本生成的后半段注意力会衰减。我一般会让 DeepSeek 先产出大纲确认结构没问题后再逐章生成。下面是一段典型的大纲编排 prompt你是开发者体验工程师。请基于以下 API 文档生成《快速开始》章节目标读者是第一次接触该平台的 Python 开发者。 章节必须包含 1. 环境准备需要哪些 SDK、密钥、基础 URL。 2. 首次请求一个完整的认证 调用示例代码必须和文档中真实存在的接口一致。 3. 常见错误至少列出 3 个新开发者最容易碰到的报错并给出解决路径。 约束 - 每个代码示例必须注明对应的接口路径。 - 不要使用请参考其他文档这类话术。 - 中文写作动词开头每段不超过 5 行。 API 文档原文 {在这里粘贴第 3 节生成的 api_docs.md 中认证章节的内容}把原文缩到最小给模型一个真实的锚点——这是生成开发者指南的关键。我见过有人直接把整本 API 文档塞进去让模型「自由发挥」结果是生成的指南里出现了 API 文档里根本不存在的「简化接口」开发者照着写代码直接 401。所以编排的原则是指南里出现的每个接口调用都必须在 API 文档里找得到出处哪怕因此牺牲掉一点文采。4.3 Markdown 转 PDFpandoc 与中文字体的血泪经验生成完 API 文档和开发者指南两个 Markdown 文件后最后一步是合成 PDF。这一步的坑集中在中文渲染上——默认的 pandoc 转 PDF 用 LaTeX 引擎对中文字体的支持需要额外配置。我的固定命令如下# 合并两个 markdown 文件按顺序合成一份开发文档 cat 00_cover.md api_docs.md developer_guide.md combined.md # 转 PDF指定 xelatex 引擎 CJK 字体 自动目录 pandoc combined.md \ --pdf-enginexelatex \ -V CJKmainfontNoto Serif CJK SC \ -V monofontNoto Sans Mono CJK SC \ -V geometry:margin2.5cm \ --toc \ --toc-depth2 \ -o 技术文档降维打击_DeepSeek自动生成API文档与开发者指南.pdfCJKmainfont指定的是中文衬线字体Windows 上通常用SimSun或Microsoft YaHeimacOS 用PingFang SCLinux 常见选择是Noto Serif CJK SC。如果字体名字写错或者系统没装对应字体xelatex 会静默失败输出一个没有中文的空 PDF——这是最隐蔽的翻车现场因为 pandoc 不会报明确错误。所以转 PDF 前先执行fc-list | grep -i Noto.*CJK确认字体存在。--toc-depth2控制目录显示到二级标题层级对于 API 文档来说刚好——一级章是文档分区二级节是接口路径太深了目录页会占好几页。geometry:margin2.5cm是页边距API 文档的代码块比较多页边距太窄会导致代码换行后缩进错乱。我吃过这个亏默认 1 英寸边距下长 URL 在代码块里被强行折行看起来像是有多余的换行符。5. 自动生成文档的五个典型翻车现场现象、原因与修复5.1unexpected status 401 unauthorized: incorrect api key provided现象调用 DeepSeek API 时返回 401报错原文形如unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****后跟一段打码的密钥前缀。原因绝大多数时候不是密钥本身错了而是环境变量优先级问题。我在脚本里用os.getenv(DEEPSEEK_API_KEY)读取密钥但 shell 里也导出了同名变量且代码里硬编码的旧密钥覆盖了环境变量——两处的值不一致API 收到的是旧密钥。解决先把密钥统一到一个.env文件用python-dotenv加载排查时在脚本入口打印密钥的前 6 位和后 4 位确认和平台上的值一致。另一个隐蔽原因是密钥复制时带了不可见空格粘贴进环境变量后肉眼看不出来建议用repr()打印检查。5.2 API 返回 400This models maximum context length is 1048576 tokens现象请求能发出去但返回 400提示当前模型最大上下文长度是 1048576 tokens而你的请求超出了实际限制。原因不是你把 1M 撑满了而是「请求总 token 数 系统提示词 历史消息 当前输入」超限。我在批量生成时把整个批次的 OpenAPI JSON 拼进 user 消息一个含大量嵌套 schema 的批次很容易瞬间吃掉十几万 token。尤其当你把前几批的响应也累加进messages时上下文会线性膨胀。解决每次请求只保留 system prompt 和当前批次的输入不要把历史输出回填到 messages 里。如果单个 path 的 schema 特别大比如 20 层嵌套把它拆到单独的批次再生成。5.3 生成的 Markdown 表格渲染后完全错位现象DeepSeek 输出的参数表格在 Markdown 预览器里行列错位竖线消失多行内容揉成一段。原因模型在连续输出长表格时偶尔会漏掉行尾的|分隔符或者某一行多写一个空格导致表格提前结束。尤其当参数超过 10 个时这种错误概率显著上升。解决不要要求模型直接生成表格而是让它输出 JSON 数组再用本地脚本转 Markdown 表格。这个技巧把「模型容易出错的结构化排版」和「机器擅长的确定性转换」分开。生成 prompt 里写「输出 JSON 数组字段名为 name/type/required/description」拿到结果后用json.loads()解析再逐行拼表。5.4 输出被截断得到一个以半句话结尾的残缺文档现象单次生成结果戛然而止结尾的 JSON 示例只输出了一半或者一句话没有句号就结束。原因max_tokens限制导致输出被强制截断但截断点并不总是出现在语义完整的边界。更隐蔽的是模型在快达到 token 上限时会「加速」结束输出导致最后一段内容明显比前面的段落更简短。解决把max_tokens从 3000 提到 4000 是治标治本是控制单批接口数量——6 个 path 一批时通常不会超过 2500 token 输出如果你发现有 path 特别长把它单独拎出来再跑一遍。同时开启streamFalse以便拿到完整的响应后再处理不要靠前端强行截断显示。5.5 文档里出现了代码中不存在的字段现象生成的接口文档里请求参数多了一个filter字段响应结构里多了一个total_pages——但打开 OpenAPI JSON 原文这些字段根本不存在。原因模型根据「常见 API 设计模式」做了推断补全。这是文档生成最危险的错误因为它带着「看起来正确」的伪装。低温度只能降低概率不能消除。解决在 system prompt 里加一条硬性约束——「禁止添加输入 JSON 之外的任何字段如果发现接口信息不完整输出信息缺失请检查 OpenAPI 源文件」。同时在生成脚本后方加一层校验把所有响应示例中的字段名抽取出来和 OpenAPI schema 里的键名做集合比对多出来的字段直接标记告警。这一条我放在 CI 里自动跑不再靠人工抽查。6. 进阶三条让文档持续可信的验证手段文档生成完只是开始真正让这套方案产生长期价值的是验证和保鲜。我目前固定跑三条检查第一条是用生成的文档里的请求示例做回放——从 Markdown 里正则抽取curl -X POST或 python 请求片段对着真实测试环境发一遍请求凡是返回 401 或 404 的示例直接标记为「文档与代码不一致」。这条检查帮我抓出过最离谱的 bug模型生成的示例里URL 路径少了一个/v1前缀。第二条是字段覆盖率统计写一个脚本枚举 OpenAPI 里全部 path 和参数名再去文档里查每个名字出现的次数覆盖率低于 90% 的接口说明文档遗漏了内容。这个数字我每周看一次低于阈值就重新生成对应章节。第三条是文档新鲜度钩子——在 git 仓库里注册一个 post-commit 钩子检测到openapi.json文件变更时自动重跑第 3 章的批量生成脚本并生成一个 diff 报告。这样文档不再是三个月前的旧货而是领着你跑的活文件。我最早的翻车经历就是把整个仓库塞给 DeepSeek结果 401 和上下文超长轮着来最后拿到一份看似完整的文档实际一半接口的示例都是模型编的。后来把「预检、生成、验证」拆开每段各守一条纪律这套流程才真正跑稳。如果你也想让团队的技术文档回到「和代码同步」的状态不妨先从一个模块的 openapi.json 开始跑通第 3 章的最小脚本再逐步铺开。希望帮到你。本文还有配套的精品资源点击获取
DeepSeek自动生成API文档与开发者指南：从OpenAPI到Markdown的完整实践
简介这份PDF聚焦如何借助DeepSeek自动生成API文档与开发者指南适合需要提升技术文档编写效率的软件工程师、技术负责人及AI工具使用者。内容从技术文档现状与挑战出发系统梳理DeepSeek核心原理、代码解析与自然语言生成机制再到环境准备、项目导入、参数设置、文档生成、审核优化等完整流程并通过实际案例比较使用前后的改进效果同时与Swagger、Sphinx等同类工具展开功能与用户体验对比归纳准确性、兼容性、性能等典型问题及对策有助于在实际项目中落地应用。文档共24页覆盖原理、实践、案例与展望目录结构清晰原理到实战完整。资源包内仅1个PDF文件大小约1.93MB查阅便捷目前已有83人学习下载适合希望通过AI辅助工具改造文档工作流、降低维护成本的开发者参考。1. 技术文档降维打击让 DeepSeek 自动生成 API 文档与开发者指南你刚把 SDK 重构完接口改了 12 处文档还停在三个月前打开旧版 API 文档发现连认证流程都是错的——这种时候 DeepSeek 自动生成 API 文档与开发者指南这整套方案解决的不只是「写文档累」而是「文档永远跟不上代码」这个工程债务。它的核心做法很直接把代码仓库里的 OpenAPI 描述、函数签名、调用示例喂给 DeepSeek让它按你给的骨架输出结构化的 Markdown再统一合成 PDF。适合手里维护着十个以上接口、却没有专职文档工程师的团队也适合把「写文档」当成 API 平台交付物一部分的后端开发者。我下面讲的每条命令和参数都是按这条路子跑过、也踩过坑的版本。2. 为什么选 DeepSeek 做文档生成先搞清「抽取」和「创作」的边界2.1 DeepSeek 在这类任务里的卡位不是聊天是结构还原做 API 文档生成最容易翻车的不是模型不会写而是模型太会写——你让它描述一个「获取用户列表」的接口它给你补出八个不存在的查询参数还配上错误码。这是因为通用模型在生成任务里默认开启「补充细节」模式而 API 文档恰恰要求「只改写、不新增」。DeepSeek 在指令跟随上的表现让「约束它不要自由发挥」这件事从玄学变成了可配置项。我的选型对比通常只看三个维度指令跟随的稳定性、中文表达的自然度、以及结构化输出JSON/Markdown的可解析性。相比之下有些模型英文文档很漂亮但中文接口说明总带着翻译腔另一些模型对话体验好但连续生成 4000 token 后表格就开始错位。DeepSeek 的上下文窗口最大能到 1M token这意味着你可以把一整份 OpenAPI JSON 原文塞进去而不是像我最初那样把代码仓库几千个文件全部丢给模型——后者会直接触发 400 错误。1M 不是给你胡乱塞东西的许可证它真正的好处是一份中等规模的 API 定义几百个 path可以整段进入上下文模型能看到接口之间的关联而不是切碎了逐条瞎猜。还有一个常被忽略的点DeepSeek 的 API 兼容 OpenAI 的调用格式你在本地开发环境里用openai这个 Python SDK只改base_url和api_key其余代码一字不动。这意味着团队里已有的 LLM 工具链可以零成本切换。如果是纯内网环境也可以用 vLLM 把开源权重部署起来SDK 调用方式不变只是base_url指向内网地址。2.2 三段式管线预检、生成、排版各干各的活很多文档自动化项目死在第一步试图让大模型直接读源码生成文档。我试过把项目根目录整个交给 DeepSeek结果有三类问题源码文件占满上下文导致关键接口信息被挤掉模型把私有方法的逻辑当成公开 API 写进文档更糟的是它会「理解」代码后自行总结接口语义而不是基于真实的接口签名来写——生成的文档看着通顺拿去对接直接报 404。所以我现在把整个过程拆成三段各用各的工具预检信息抽取用 FastAPI 自带的 OpenAPI 生成、Spring Doc、或者 apibuilder 这类工具把代码里的路由、参数、返回结构固化成openapi.json。这一步不经过任何模型保证信息源是「代码事实」而不是「模型理解」。生成LLM 改写把精简过的 OpenAPI 片段 写作规范 prompt 交给 DeepSeek让它产出 Markdown。这里的核心约束是模型只能基于给定的 JSON 做复述和解释不能新增字段。排版文档合成把 DeepSeek 生成的多个 Markdown 文件用 pandoc 合并成 PDF统一目录、页眉和代码样式。这个拆分不是为了炫技而是为了出问题时能定位。预检环节出错是工具配置问题生成环节出错是 prompt 或参数问题排版出错是样式问题。三段各自独立可重跑不会互相污染。2.3 写作规范先行prompt 是唯一的生产资料在写任何调用代码之前先把写作规范固化成一个 system prompt。我参考中文技术文档写作规范里的约定动词开头、每段只说一件事、参数说明必须给类型和取值范围、代码示例必须带注释。这些规则直接写进 prompt而不是期望模型「懂规矩」。下面是我常用的 system prompt 模板SYSTEM_PROMPT 你是一名资深 API 文档工程师。你的任务是基于给定的 OpenAPI 片段生成中文接口文档。 写作规范必须遵守 1. 只描述输入 JSON 中真实存在的字段禁止补充、推断或根据常识添加任何参数。 2. 每个参数必须包含参数名、类型、是否必填、取值范围、默认值如有、含义。 3. 响应示例必须和输入 JSON 中的 schema 完全一致可以简化嵌套层级但不能改字段名。 4. 用中文写作动词开头如获取用户列表创建订单每段不超过 5 行。 5. 禁止使用等等可能大概这类模糊词。 6. 输出格式为 Markdown标题层级从 ### 开始。 输入数据格式 - 接口路径、方法、请求参数、响应结构均来自 OpenAPI JSON 原文。 - 若 OpenAPI 片段为空直接输出无可用信息不编造。 这段 prompt 里最重要的不是前五条规范而是第六条和「若 OpenAPI 片段为空」这句话——它把模型的自由度压到最低。没有这条兜底模型遇到缺失信息就会自动脑补后续你在文档里看到不存在的字段时根本分不清是代码问题还是文档问题。调用时的参数我一般固定在temperature0.2偏低保证确定性、max_tokens3000防止单次输出过长截断、top_p0.5。这些参数不是玄学后面我会讲到它们各自卡住了哪些典型故障。3. 用 DeepSeek 自动生成 API 文档从 openapi.json 到可发布 Markdown3.1 预检先把代码固化成 OpenAPI 描述文件无论你用什么语言写后端第一件事永远是拿到一份忠实描述接口的 OpenAPI JSON。以 FastAPI 为例框架会帮你自动生成并挂在/openapi.json路由上但这份文件通常包含大量components.schemas定义直接喂给模型会浪费 token 且容易超出上下文限制。我一般会先跑一个精简脚本只保留生成文档真正需要的字段import json def compact_openapi(src_path: str, dst_path: str): 压缩 OpenAPI 描述去掉无用的扩展字段保留 paths 和精简后的 schemas with open(src_path, r, encodingutf-8) as f: spec json.load(f) # 保留接口定义主体剔除 swagger 扩展信息 compact { openapi: spec.get(openapi, 3.0.0), info: spec.get(info, {}), paths: spec.get(paths, {}), components: {schemas: spec.get(components, {}).get(schemas, {})} } with open(dst_path, w, encodingutf-8) as f: json.dump(compact, f, ensure_asciiFalse, indent2) # 统计接口数量与 schema 数量作为后续分批的参考 print(fpaths: {len(compact[paths])}) print(fschemas: {len(compact[components][schemas])}) # 用法示例读取 fastapi 生成的 openapi.json输出精简版 compact_openapi(openapi_raw.json, openapi_compact.json)这段脚本的作用是把原始 OpenAPI 文件里的冗余扩展字段比如x-openapi-router-controller、x-codegen-request-body-name这一类框架注入信息剥掉。保留info是因为文档头部需要版本号和描述保留paths是因为接口路径和 HTTP 方法是文档的核心骨架保留components.schemas是因为响应结构定义要从这里引用。跑完脚本后打印的 path 数量直接决定你下一步怎么分批调用 DeepSeek——我的经验是每批 5 到 8 个 path 最合适太少浪费请求次数太多则单次响应容易超时或截断。如果你维护的是老项目没有现成的/openapi.json常见做法是引入 SpringDocJava、Swagger 注解Node.js、或者用 apibuilder 从路由代码反向生成。这一步别指望模型替你完成原因前面说过模型读源码生成的接口定义本质是「推断」而文档需要的是「事实」。预检环节宁可多花一小时把工具配好也不要省这个功夫让模型编。3.2 核心生成脚本DeepSeek API 调用的最小可跑通版本拿到精简后的 OpenAPI 文件下一步就是写生成脚本。这里我直接用openaiSDK通过base_url指向 DeepSeek 的 API 端点。完整代码如下关键位置都加了注释import json import time from openai import OpenAI # DeepSeek API 兼容 OpenAI 格式仅需替换 base_url 与 api_key client OpenAI( api_keysk-你的密钥, # 从 DeepSeek 开放平台获取不要在代码里硬编码 base_urlhttps://api.deepseek.com/v1 # 注意是 /v1 结尾 ) SYSTEM_PROMPT 这里粘贴上一节的完整 system prompt def generate_api_doc(path_block: dict) - str: 输入一个包含多个 path 的字典输出该批接口的 Markdown 文档 block_json json.dumps(path_block, ensure_asciiFalse, indent2) response client.chat.completions.create( modeldeepseek-chat, # 通用对话模型文本生成任务选这个 messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: f请基于以下 OpenAPI 片段生成接口文档\n{block_json}} ], temperature0.2, # 偏低温度减少自由发挥 max_tokens3000, # 限制单次输出长度 top_p0.5, # 核采样配合低温度进一步压稳 streamFalse # 关闭流式便于直接拿到完整结果 ) return response.choices[0].message.content # 分批处理每 6 个 path 一批累计结果 def batch_generate(compact_path: str, output_path: str, batch_size: int 6): with open(compact_path, r, encodingutf-8) as f: spec json.load(f) paths spec[paths] path_items list(paths.items()) doc_sections [f# {spec[info].get(title, API Reference)}\n] for i in range(0, len(path_items), batch_size): batch dict(path_items[i:i batch_size]) print(f正在生成第 {i // batch_size 1} 批 f共 {len(batch)} 个接口{i}~{i len(batch)}) for attempt in range(3): # 失败重试最多 3 次 try: markdown generate_api_doc(batch) doc_sections.append(markdown) break except Exception as e: print(f第 {attempt 1} 次调用失败{e}) time.sleep(2) # 退避 2 秒再重试 else: print(f批次 {i // batch_size 1} 连续 3 次失败跳过) with open(output_path, w, encodingutf-8) as f: f.write(\n\n.join(doc_sections)) print(f文档已写入{output_path}) if __name__ __main__: batch_generate(openapi_compact.json, api_docs.md)这段代码遵循一个原则api_key不该硬编码在源码里。你可以通过环境变量DEEPSEEK_API_KEY读取这样至少不会把密钥提交进 git。其次batch_generate里的time.sleep(2)不是多余的——DeepSeek API 在持续高并发下偶发 429 限流短退避比立刻重试成功率高得多。至于max_tokens3000我特意限制单次输出长度因为它直接关系到下一个坑如果模型输出被截断你拿到的是一段以半个 JSON 结尾的碎文档而这在max_tokens设得过大时反而不容易察觉。调用完成后你会得到一个api_docs.md里面是按批次生成的接口说明。max_tokens的设定比你以为的更重要设得太小长接口的响应示例会被切半设得太大比如 8000一旦模型开始重复输出浪费的 token 会让账单难看而且超长输出的稳定性反而下降。3.3 参数设置与成本控制api 调用量和价格都藏在细节里DeepSeek 按 token 计费文档生成这种任务的特点是「输入大、输出可控」。我见过有人把未精简的原始 OpenAPI 直接喂进去一个接口带五个嵌套的 schema每次调用重复传相同的components.schemasapi 调用量直接翻三倍。常见做法是预检时把每个接口要用的 schema 引用提前解析出来拼到对应的 path 块里而不是整份 schemas 一起塞。另一个控制成本的参数是top_p。在文档生成场景里top_p0.5配合temperature0.2比单独把温度调到 0 的效果更稳——因为温度归零会让模型在长文本里陷入重复循环而核采样限制的是候选词集合两者精细配合后输出质量既稳定又不呆板。下面的表格是我在几次迭代后固定的推荐参数参数推荐值作用调低/调高的后果temperature0.2控制随机性调至 0 易重复高于 0.5 开始出现编造字段top_p0.5限制候选词集合调高到 0.9 后输出多样性提升但结构稳定性下降max_tokens3000限制单次输出长度过小截断过大遇到重复输出时浪费计费batch_size5~8 path/批控制单次输入规模过小请求次数多过大单次响应时间变长还有一条经验同一个 system prompt 在连续多次请求时DeepSeek 会命中上下文缓存这部分 token 计费有折扣。所以你在循环里应该把SYSTEM_PROMPT保持字符串完全一致不要因为代码格式化而把换行或空格改掉——缓存是按前缀精确匹配的任何字符差异都会导致缓存失效重新计费。4. 从 API 文档到开发者指南结构编排与 PDF 落地4.1 两种文档两种受众API Reference 不等于开发者指南很多团队把 API 文档和开发者指南混为一谈生成一份文档就想两边复用。实际上这就像拿 CMOS sensor 的技术手册去教硬件工程师做调试——信息都在但排布方式完全不对。API 文档解决的是「某个接口怎么调」它的颗粒度是单个 path开发者指南解决的是「一个完整流程怎么走通」它的颗粒度是「认证 → 第一次请求 → 分页 → 错误处理」。DeepSeek 在生成这两类文档时需要完全不同的 prompt 和完全不同的结构化约束。维度API 文档开发者指南读者对接第三方系统的工程师刚接触平台的新手开发者核心问题这个接口的参数和返回是什么我怎么用这套 API 完成一个真实功能起点数据OpenAPI JSON 的 paths 片段一组典型业务场景的描述输出结构按 path 分节按「快速开始→认证→核心流程→错误排查」分章模型自由度低只能复述给定 JSON中可补充流程性描述我的做法是分两阶段生成先用 DeepSeek 从 API 文档里提炼出「典型调用链」再基于调用链生成开发者指南。这样可以避免模型在写指南时凭空发明接口——凡是指南里出现的示例代码都必须在 API 文档里能找到对应的接口定义。这条约束写进 prompt后续可以拿脚本自动校验。4.2 编排生成指南先给骨架再填肉开发者指南如果一次性让模型生成整篇文章往往会出现「开头详细、结尾潦草」的问题因为长文本生成的后半段注意力会衰减。我一般会让 DeepSeek 先产出大纲确认结构没问题后再逐章生成。下面是一段典型的大纲编排 prompt你是开发者体验工程师。请基于以下 API 文档生成《快速开始》章节目标读者是第一次接触该平台的 Python 开发者。 章节必须包含 1. 环境准备需要哪些 SDK、密钥、基础 URL。 2. 首次请求一个完整的认证 调用示例代码必须和文档中真实存在的接口一致。 3. 常见错误至少列出 3 个新开发者最容易碰到的报错并给出解决路径。 约束 - 每个代码示例必须注明对应的接口路径。 - 不要使用请参考其他文档这类话术。 - 中文写作动词开头每段不超过 5 行。 API 文档原文 {在这里粘贴第 3 节生成的 api_docs.md 中认证章节的内容}把原文缩到最小给模型一个真实的锚点——这是生成开发者指南的关键。我见过有人直接把整本 API 文档塞进去让模型「自由发挥」结果是生成的指南里出现了 API 文档里根本不存在的「简化接口」开发者照着写代码直接 401。所以编排的原则是指南里出现的每个接口调用都必须在 API 文档里找得到出处哪怕因此牺牲掉一点文采。4.3 Markdown 转 PDFpandoc 与中文字体的血泪经验生成完 API 文档和开发者指南两个 Markdown 文件后最后一步是合成 PDF。这一步的坑集中在中文渲染上——默认的 pandoc 转 PDF 用 LaTeX 引擎对中文字体的支持需要额外配置。我的固定命令如下# 合并两个 markdown 文件按顺序合成一份开发文档 cat 00_cover.md api_docs.md developer_guide.md combined.md # 转 PDF指定 xelatex 引擎 CJK 字体 自动目录 pandoc combined.md \ --pdf-enginexelatex \ -V CJKmainfontNoto Serif CJK SC \ -V monofontNoto Sans Mono CJK SC \ -V geometry:margin2.5cm \ --toc \ --toc-depth2 \ -o 技术文档降维打击_DeepSeek自动生成API文档与开发者指南.pdfCJKmainfont指定的是中文衬线字体Windows 上通常用SimSun或Microsoft YaHeimacOS 用PingFang SCLinux 常见选择是Noto Serif CJK SC。如果字体名字写错或者系统没装对应字体xelatex 会静默失败输出一个没有中文的空 PDF——这是最隐蔽的翻车现场因为 pandoc 不会报明确错误。所以转 PDF 前先执行fc-list | grep -i Noto.*CJK确认字体存在。--toc-depth2控制目录显示到二级标题层级对于 API 文档来说刚好——一级章是文档分区二级节是接口路径太深了目录页会占好几页。geometry:margin2.5cm是页边距API 文档的代码块比较多页边距太窄会导致代码换行后缩进错乱。我吃过这个亏默认 1 英寸边距下长 URL 在代码块里被强行折行看起来像是有多余的换行符。5. 自动生成文档的五个典型翻车现场现象、原因与修复5.1unexpected status 401 unauthorized: incorrect api key provided现象调用 DeepSeek API 时返回 401报错原文形如unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****后跟一段打码的密钥前缀。原因绝大多数时候不是密钥本身错了而是环境变量优先级问题。我在脚本里用os.getenv(DEEPSEEK_API_KEY)读取密钥但 shell 里也导出了同名变量且代码里硬编码的旧密钥覆盖了环境变量——两处的值不一致API 收到的是旧密钥。解决先把密钥统一到一个.env文件用python-dotenv加载排查时在脚本入口打印密钥的前 6 位和后 4 位确认和平台上的值一致。另一个隐蔽原因是密钥复制时带了不可见空格粘贴进环境变量后肉眼看不出来建议用repr()打印检查。5.2 API 返回 400This models maximum context length is 1048576 tokens现象请求能发出去但返回 400提示当前模型最大上下文长度是 1048576 tokens而你的请求超出了实际限制。原因不是你把 1M 撑满了而是「请求总 token 数 系统提示词 历史消息 当前输入」超限。我在批量生成时把整个批次的 OpenAPI JSON 拼进 user 消息一个含大量嵌套 schema 的批次很容易瞬间吃掉十几万 token。尤其当你把前几批的响应也累加进messages时上下文会线性膨胀。解决每次请求只保留 system prompt 和当前批次的输入不要把历史输出回填到 messages 里。如果单个 path 的 schema 特别大比如 20 层嵌套把它拆到单独的批次再生成。5.3 生成的 Markdown 表格渲染后完全错位现象DeepSeek 输出的参数表格在 Markdown 预览器里行列错位竖线消失多行内容揉成一段。原因模型在连续输出长表格时偶尔会漏掉行尾的|分隔符或者某一行多写一个空格导致表格提前结束。尤其当参数超过 10 个时这种错误概率显著上升。解决不要要求模型直接生成表格而是让它输出 JSON 数组再用本地脚本转 Markdown 表格。这个技巧把「模型容易出错的结构化排版」和「机器擅长的确定性转换」分开。生成 prompt 里写「输出 JSON 数组字段名为 name/type/required/description」拿到结果后用json.loads()解析再逐行拼表。5.4 输出被截断得到一个以半句话结尾的残缺文档现象单次生成结果戛然而止结尾的 JSON 示例只输出了一半或者一句话没有句号就结束。原因max_tokens限制导致输出被强制截断但截断点并不总是出现在语义完整的边界。更隐蔽的是模型在快达到 token 上限时会「加速」结束输出导致最后一段内容明显比前面的段落更简短。解决把max_tokens从 3000 提到 4000 是治标治本是控制单批接口数量——6 个 path 一批时通常不会超过 2500 token 输出如果你发现有 path 特别长把它单独拎出来再跑一遍。同时开启streamFalse以便拿到完整的响应后再处理不要靠前端强行截断显示。5.5 文档里出现了代码中不存在的字段现象生成的接口文档里请求参数多了一个filter字段响应结构里多了一个total_pages——但打开 OpenAPI JSON 原文这些字段根本不存在。原因模型根据「常见 API 设计模式」做了推断补全。这是文档生成最危险的错误因为它带着「看起来正确」的伪装。低温度只能降低概率不能消除。解决在 system prompt 里加一条硬性约束——「禁止添加输入 JSON 之外的任何字段如果发现接口信息不完整输出信息缺失请检查 OpenAPI 源文件」。同时在生成脚本后方加一层校验把所有响应示例中的字段名抽取出来和 OpenAPI schema 里的键名做集合比对多出来的字段直接标记告警。这一条我放在 CI 里自动跑不再靠人工抽查。6. 进阶三条让文档持续可信的验证手段文档生成完只是开始真正让这套方案产生长期价值的是验证和保鲜。我目前固定跑三条检查第一条是用生成的文档里的请求示例做回放——从 Markdown 里正则抽取curl -X POST或 python 请求片段对着真实测试环境发一遍请求凡是返回 401 或 404 的示例直接标记为「文档与代码不一致」。这条检查帮我抓出过最离谱的 bug模型生成的示例里URL 路径少了一个/v1前缀。第二条是字段覆盖率统计写一个脚本枚举 OpenAPI 里全部 path 和参数名再去文档里查每个名字出现的次数覆盖率低于 90% 的接口说明文档遗漏了内容。这个数字我每周看一次低于阈值就重新生成对应章节。第三条是文档新鲜度钩子——在 git 仓库里注册一个 post-commit 钩子检测到openapi.json文件变更时自动重跑第 3 章的批量生成脚本并生成一个 diff 报告。这样文档不再是三个月前的旧货而是领着你跑的活文件。我最早的翻车经历就是把整个仓库塞给 DeepSeek结果 401 和上下文超长轮着来最后拿到一份看似完整的文档实际一半接口的示例都是模型编的。后来把「预检、生成、验证」拆开每段各守一条纪律这套流程才真正跑稳。如果你也想让团队的技术文档回到「和代码同步」的状态不妨先从一个模块的 openapi.json 开始跑通第 3 章的最小脚本再逐步铺开。希望帮到你。本文还有配套的精品资源点击获取
