简介技术文档的维护是开发团队长期面临的痛点接口变更频繁人工更新文档往往滞后导致文档与代码脱节。OpenAPI/Swagger 规范虽然能描述接口结构却无法自动生成解释性内容。借助 DeepSeek 等大语言模型可以将接口定义、代码注释与历史问答等资料整合起来自动生成结构清晰、包含示例与注意事项的开发者指南。通过构建从输入整理、结构化输出到 Markdown 转 PDF 的自动化流水线配合 Pandoc 与 CI 定时任务接口文档可以实现持续更新显著降低维护成本让开发者将精力聚焦于核心业务。这一实践思路深入解析了如何用 DeepSeek 搭建一套稳定、可复用的 API 文档自动生成方案。1. 技术文档降维打击DeepSeek自动生成API文档与开发者指南.pdf我见过太多 API 文档翻车现场接口上线一个月文档里还写着旧字段开发者追着后端问“这个参数到底传不传”后端打开 IDE 翻三分钟源码才给出答案。技术文档降维打击DeepSeek自动生成API文档与开发者指南.pdf 这个标题说的不是拿模型写两段俏皮话而是把 OpenAPI/Swagger、代码注释、历史问答这些真实资料吃进去自动产出接口说明、示例代码、错误码表最后落成一份带书签的 PDF。适合后端工程师、技术写手也适合一个人包干全栈文档的独立开发者。读完你不只能调通接口还能搭出一条每次发布都自动更新的文档流水线。这里的关键是模型写文档只是一次调用真正花时间的是输入整理、输出校验、Markdown 转 PDF 和后续维护。先把原理和选型讲清楚再给一套能直接跑起来的管道。2. 为什么用 DeepSeek 生成技术文档先解决“该不该自动化”的问题2.1 技术文档的痛点文档必腐模型怎么解决只要接口在演进文档就会腐化。字段改了没人及时同步、废弃接口没有标注、新同事照着文档调接口调出 400这些都是常态。Swagger/OpenAPI 能自动生成字段名、类型、必填项但它回答不了“为什么这个接口要分页”“什么时候应该重试”“这个字段和另一个字段是什么关系”。这些解释性内容过去靠人写而人写文档的速度永远追不上代码变更速度所以大多数团队的 API 文档都停在“能用但没人想打开”的状态。DeepSeek 这类模型真正解决的不是“从无到有写文档”而是“把散落在各处的信息整理成文档”。接口定义在 OpenAPI 里、边界条件写在代码注释里、调用技巧藏在聊天记录和工单里模型能一次性读入这些输入按你指定的结构输出。它比模板生成强的地方是模板只能填字段模型可以解释、举例子、补边界情况提示。但要注意模型不知道你公司内部的鉴权规则、历史包袱和业务语义这些必须通过 Prompt 或预处理喂给它。喂得越干净输出越靠谱。维度模板生成DeepSeek 生成字段准确性高直接取自规范中高取决于输入整理和校验描述丰富度低只能填空高能生成概述、示例、注意事项更新成本仍需人工组织内容输入更新后全自动重写输出格式固定可通过 Prompt 和代码约束适合场景纯参数查询面向开发者的完整指南选 DeepSeek 而不是其他模型实用理由有三条上下文窗口比早期大模型宽能吞下一整套接口定义中文表述适合给国内团队看接口兼容 OpenAI 协议写过的代码几乎不用改只需要换 base_url 和 key。如果你已经把旧文档在内部 Wiki 里沉淀了一两年把这些文档当作“语料”灌进 Prompt生成的初稿质量会明显高于从零硬写。2.2 一个能落地的 Prompt 结构角色、输入、输出约束Prompt 直接影响文档能不能直接进 PDF。我试过最省心的结构是四段式角色、任务、输入、硬性约束。先给一个能快速验证的版本API_DOC_PROMPT 你是一名 API 文档工程师专门为后端开发者撰写接口文档。 请根据下面的接口信息输出一份面向调用方的接口说明文档。 输出要求 1. 只根据输入信息写作严禁新增不存在的字段、参数、状态码。 2. 全部用中文语言简洁避免废话。 3. 每个接口必须包含以下小节 - 功能概述 - 参数说明 - 请求示例 - 响应示例 - 调用注意 4. 请求和响应示例用 JSON 字符串形式写在对应字段里不要直接输出 Markdown 代码块。 5. 对不确定的内容写「建议与后端确认」不要自行推断。 接口信息 {interface} 这段 Prompt 的核心不是“请生成文档”而是把“不要瞎编”和“代码块从哪来”写清楚。尤其第 4 条很关键如果让模型直接输出三个反引号包裹的 Markdown后面合并大文档时会炸这个坑在第五节细说。参数说明部分要给出每个参数的默认值、是否必填、类型这些在输入整理阶段就得准备好不能靠模型自己猜。如果发现生成结果经常漏掉某个小节不要只加一行“记住带上调用注意”更好的办法是在 Prompt 最后附一个极短的示例片段比如“调用注意示例- 新增字段需要开启 v2 版本”。模型对示例的跟随能力比对抽象规则的跟随能力强得多。这个技巧在后续 3.2 生产环境的结构化输出里同样有效。2.3 调用 DeepSeek API 的最小命令参数设置与错误预期先不引入复杂依赖用 requests 调用一个 OpenAI 兼容的 chat completions 接口就够了。import os import requests def call_deepseek(prompt: str) - str: resp requests.post( os.environ[DEEPSEEK_BASE_URL] /chat/completions, headers{Authorization: fBearer {os.environ[DEEPSEEK_API_KEY]}}, json{ model: os.environ.get(DEEPSEEK_MODEL, deepseek-chat), messages: [{role: user, content: prompt}], temperature: 0.2, max_tokens: 2000, }, timeout120, ) if resp.status_code ! 200: raise RuntimeError(f{resp.status_code}: {resp.text}) return resp.json()[choices][0][message][content]这里要解释几个参数。temperature: 0.2让输出更稳定文档生成不需要高随机性如果你想要更“有创造性”的表述可以调到 0.5但过高的温度很容易编字段名。max_tokens: 2000不是越大越好它只是单次回复上限真正的总 token 会受模型上下文窗口限制这就是 5.2 节要讲的问题。timeout: 120是因为长输出很可能超过常规的 30 秒特别是接口定义很大的时候。跑之前先设置环境变量DEEPSEEK_API_KEY和DEEPSEEK_BASE_URL。如果遇到401 unauthorized: incorrect api key provided之类的错误先检查 key 是否有空格、环境变量是否真的被当前 shell 读到、base_url 是否正确。这是整个流程里最容易踩的门槛我会在第 5 章里专门展开。另外建议在函数开头加一个简单的连接异常处理requests.exceptions.ConnectionError出现时至少能打印出“网络层失败确认 outbound 访问是否放通”的提示而不是抛一个裸 stack trace。3. 从 API 定义到开发者指南搭建自动生成管道3.1 输入整理把 OpenAPI/Swagger 转成模型可用的“中间表示”直接把整个 OpenAPI JSON 丢给 DeepSeek不是不行而是容易超 token、容易胡编。模型读到一堆$ref和 schema 嵌套之后经常找不到重点。所以第一步是把 OpenAPI 压成“接口级摘要”一个路径对应一个方法只留路径、方法、概览、参数、请求体、响应说明。import json def extract_interfaces(openapi_path: str) - list: with open(openapi_path, r, encodingutf-8) as f: spec json.load(f) interfaces [] for path, methods in spec.get(paths, {}).items(): for method in (get, post, put, delete, patch): op methods.get(method) if not op: continue interfaces.append({ method: method.upper(), path: path, summary: op.get(summary, ), description: op.get(description, ), parameters: op.get(parameters, []), requestBody: op.get(requestBody, {}), responses: {str(k): v.get(description, ) for k, v in op.get(responses, {}).items()}, }) return interfaces这段代码做了三件有意义的事。第一只提取知道要展示的字段把 OpenAPI 里那些全局组件、扩展字段全丢到外面。第二把requestBody保留成原样 JSON方便模型理解结构但注意有的$ref还要继续展开否则模型看到一个$ref不知道里面是什么。第三responses被简化成状态码到描述的映射因为完整响应体通常太长。如果接口特别多可以在这里加一个过滤条件只保留summary非空的接口这些往往才是需要文档覆盖的核心入口。如果 OpenAPI 里大量使用$ref我建议在调用模型之前做一次浅递归展开。下面这个辅助函数能解决大部分引用def resolve_ref(node, spec, depth0): if depth 5: return {$ref_too_deep: node.get($ref, )} if isinstance(node, dict) and $ref in node: ref_path node[$ref].lstrip(#/).split(/) target spec for key in ref_path: target target[key] return resolve_ref(target, spec, depth 1) if isinstance(node, dict): return {k: resolve_ref(v, spec, depth 1) for k, v in node.items()} if isinstance(node, list): return [resolve_ref(i, spec, depth 1) for i in node] return node把展开后的结果传给模型幻觉会明显变少。要注意深度限制我一般限制在 5 层防止循环引用把进程跑死。这个函数放在extract_interfaces提取parameters和requestBody时调用即可。3.2 批量生成让 DeepSeek 输出结构化 JSON再转成 Markdown这里要强调一个从踩坑里换来的习惯别让模型直接输出一整篇 Markdown而是让它输出结构化 JSON由本地脚本负责包装成文档。这样代码块不会嵌套错乱后续校验也容易。import json import re import time from pathlib import Path SECTION_PROMPT 你是 API 文档工程师。根据下面的接口信息输出一个 JSON 对象。 JSON 必须包含这些字段 - title: 接口标题 - overview: 功能概述 - params: 参数说明每项包含 name, type, required, description - request_example: 请求示例是一个 JSON 字符串不要包含 Markdown 围栏 - response_example: 响应示例同样是一个 JSON 字符串 - notice: 调用注意数组每项一句话 接口信息 {interface} .strip() def clean_json(raw: str) - dict: # 模型偶尔会带 json 围栏去掉它们再解析 raw re.sub(r^(?:json)?\s*|\s*$, , raw.strip(), flagsre.S) return json.loads(raw) def generate_section(interface: dict) - dict: prompt SECTION_PROMPT.format(interfacejson.dumps(interface, ensure_asciiFalse, indent2)) raw call_deepseek(prompt) return clean_json(raw) def section_to_md(section: dict) - str: lines [] lines.append(f### {section[title]}) lines.append() lines.append(section[overview]) lines.append() lines.append(#### 参数说明) for p in section.get(params, []): lines.append(f- {p[name]}{p[type]}{必填 if p[required] else 选填}{p[description]}) lines.append() lines.append(#### 请求示例) lines.append() lines.append(json) lines.append(section[request_example]) lines.append() lines.append() lines.append(#### 响应示例) lines.append() lines.append(json) lines.append(section[response_example]) lines.append() if section.get(notice): lines.append() lines.append(#### 调用注意) for n in section[notice]: lines.append(f- {n}) lines.append() return \n.join(lines)这里的核心是clean_json。模型输出在极端情况下会在 JSON 外面包三个反引号这个正则把它们剥掉只留中间 JSON。section_to_md才是在固定安全的位置写json围栏的地方这样即使模型在request_example里写了反引号也只是普通字符不会破坏文档结构。注意我在section_to_md里仍然写了#### 参数说明这会在 PDF 里变成四级标题配合--toc-depth2不会进入目录所以正文里保留是安全的。批量跑的时候保持串行每轮之间 sleep 0.5 秒def batch_generate(interfaces: list, output_dir: Path) - None: output_dir.mkdir(parentsTrue, exist_okTrue) for i, interface in enumerate(interfaces): section generate_section(interface) md section_to_md(section) fname f{i:03d}_{interface[method]}_{interface[path].replace(/, _)}.md (output_dir / fname).write_text(md, encodingutf-8) print(f[{i1}/{len(interfaces)}] {interface[method]} {interface[path]}) time.sleep(0.5)串行慢一点但稳定胜在不容易半夜起来看限流报错。如果接口上百个可以改用线程池并发但要注意 API 账户的 RPM 限制达到限制后会连续报 429。我一般会把 sleep 提到 1 秒宁可多等十分钟也不愿意生成到一半被限流重跑。3.3 输出组装把生成的 Markdown 拼成完整文档单个接口的片段生成之后需要一个合并脚本把它们拼成一个api-reference.md。这里注意目录不要自己拼交给 Pandoc 的--toc自动生成才能和最终 PDF 书签对齐。def merge_sections(docs_dir: Path, output_md: Path) - None: files sorted(docs_dir.glob(*.md)) with open(output_md, w, encodingutf-8) as out: out.write(# API 开发者指南\n\n) out.write( 本指南由 DeepSeek 自动生成人工审核后发布。\n\n) out.write(## 接口列表\n\n) for f in files: first_line f.read_text(encodingutf-8).splitlines()[0] title first_line.lstrip(# ).strip() out.write(f- {title}\n) out.write(\n---\n\n) for f in files: out.write(f.read_text(encodingutf-8)) out.write(\n\n---\n\n)排序按照00x_...文件名来也就是提取接口的顺序。如果希望按模块分组可以改文件名的前缀规则比如把路径第一段作为目录名但这会引入更多处理逻辑。第一个版本先平铺能跑通最重要。合并后的 Markdown 不需要自己写锚点目录Pandoc 在生成 PDF 时会根据标题结构自动做目录和书签。合并脚本跑完之后我习惯顺手生成一个review_checklist.md把每个接口是否包含五个必需小节的检查结果输出出来作为人工审核时的快速参考。这个脚本很简单读每个片段检查有没有“功能概述”“参数说明”“请求示例”“响应示例”“调用注意”这几个标题缺了就列出文件名。只要这一步过了生成 PDF 之前就不会再被格式问题打断。4. 把 Markdown 转成开发者指南 PDF排版那层“玄学”4.1 Markdown 到 PDF 选型Pandoc LaTeX vs 浏览器打印生成 Markdown 之后接下来就是“怎么变成 PDF”。最省事的方法是用浏览器打开 Markdown 然后打印成 PDF但分页和目录很不可控而且中文代码块容易在换页时被截断。我的做法是用 Pandoc XeLaTeX所有排版规则都在命令行里控制出一版和一版长一样适合交付。可能有人会问为什么不直接从 Swagger UI 导出 PDF答案很简单Swagger UI 的核心是交互式调试导出来的内容只有路径列表和参数表没有概览、调用注意、示例代码。你想要的是一份能发给新同事当入门手册的开发者指南而不是一张接口清单。Pandoc 的价值在于把 Markdown 的标题、表格、代码块映射到 LaTeX 的章节、长表和代码环境自动化程度高且不依赖 GUI。方案目录/书签代码高亮中文支持自动化程度浏览器打印弱跟随主题好低需要人工点击Pandoc XeLaTeX自动 TOC支持多个主题需配置 CJK 字体高一条命令Typora 导出好好好中依赖 GUI4.2 中文排版参数字体、代码块、表格换行用 Pandoc 默认引擎直接转中文大概率得到方块字。原因不是 Pandoc 不支持中文而是 LaTeX 默认字体里没有 CJK 字形。所以必须指定--pdf-enginexelatex同时给CJKmainfont指定一个系统里存在的中文字体。先检查系统里有什么中文字体fc-list :langzh | head -20常见的可选项有Noto Sans CJK SC、Source Han Sans SC、Source Han Serif SC。没有安装的话用包管理器装一下或者下载开源思源字体放到~/.fonts下刷新字体缓存后 Pandoc 就能认到。选字体不只是为了“好看”更直接影响 PDF 的体积和渲染速度。黑体更适合接口文档标题用粗体、正文用常规就能看出层级。表格换行是另一个容易翻车的点。Pandoc 默认会把超过页宽的表格横向溢出要么冲出页面要么显示成一行很挤的文字。别依赖 Pandoc 自动缩小字号最可靠的办法是在 Markdown 侧就控制列数。接口文档里的参数表我一般不超过五列名称、类型、必填、默认值、描述。描述里不要写太长句子超过 40 个字就拆成要点或者挪到正文里展开。4.3 一个可复用的打包命令把整个构建过程收敛成一个脚本发布时只跑这一条命令#!/usr/bin/env bash # build_pdf.sh FONT_NAME${FONT_NAME:-Noto Sans CJK SC} MONO_FONT${MONO_FONT:-Noto Sans Mono CJK SC} pandoc \ api-reference.md \ -o api-reference.pdf \ --pdf-enginexelatex \ --toc \ --toc-depth2 \ --highlight-styletango \ -V documentclassarticle \ -V fontsize10pt \ -V geometry:margin2cm \ -V CJKmainfont$FONT_NAME \ -V mainfont$FONT_NAME \ -V monofont$MONO_FONT \ -V colorlinkstrue \ -V linkcolorBlue--toc-depth2让目录只到二级标题接口 demo 的三级标题不用全列进去不然目录比正文还长。tango是 Pandoc 自带的代码高亮风格属于比较耐看的默认项。geometry:margin2cm控制页边距正式发布时可以收紧到 1.8cm打印装订则建议留 2.5cm。colorlinkstrue和linkcolorBlue保证 PDF 里的内部链接和外部 URL 是蓝色可点而不是默认的红色方框。如果运行时提示找不到字体先不要急着换字体名字执行fc-cache -fv刷新字体缓存再重新跑。如果仍然报错cannot find用fc-list | grep -i Noto Sans确认准确名称有时候发行版把字体打包成Noto Sans CJKsc之类的变体。这个脚本我用了很久唯一一次翻车就是字体名字敲错。5. 避坑指南DeepSeek 生成 API 文档的 5 个常见问题5.1 现象请求返回 401 unauthorized 或 incorrect api key现象第一次跑call_deepseek返回unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****。原因绝大多数时候是环境变量没传对。要么DEEPSEEK_API_KEY没export到当前 shell要么 key 复制时带了空格或换行要么 base_url 拼错了路径。解决先用echo ${DEEPSEEK_API_KEY} | cat -A看看行尾是否有^M或空格key 从控制台复制时不要用 Word 或笔记软件粘贴容易混入不可见字符。再用env | grep -c DEEPSEEK_API_KEY确认当前 shell 确实读到了变量。base_url 不要重复写/v1或者/api确认拼接后的完整地址能通过一份最简 curl 请求拿到正常响应。最后看一眼账户是否欠费或 key 被重置API key 失效这种事隔几个月总会遇到一次。5.2 现象长上下文被截断返回 “maximum context length”现象调用返回api error: 400 this models maximum context length is 1048576 tokens. however之类的错误后半句通常提示你输入太长。原因把整份 OpenAPI 文件、几个版本的旧文档、甚至源代码全塞进了同一段 prompt。上下文窗口再大也是有限度的模型处理超长输入时会直接拒绝。解决回到 3.1 的整理脚本只保留路径、方法、参数名、简述和响应码。如果接口 schema 嵌套很深把$ref展开一两层之后截断单个接口的 prompt 里只放该接口的片段不要放其他接口。还有一个容易忽略的点max_tokens设置过大也会触发这个错误因为输入 token 加输出 token 的总量不能超过模型上下文上限。先把max_tokens从 2000 降到 1000 试试如果还是超就切输入。我习惯在调用前加一个字符数检查if len(json.dumps(interface, ensure_asciiFalse)) 6000: 截断 description。这是一个很笨但有效的护栏避免单个接口把几万字符的嵌套 schema 全喂进去。真正的生产环境还会按接口大小动态调整每次调用内容比如把过大的requestBody降级成只保留顶层字段名。5.3 现象生成内容一本正经胡说八道现象文档里出现了page_size参数但 OpenAPI 原文里只有limit或者响应示例里冒出201 Created但实际接口只定义了200/400/500。原因模型在没把握的地方用自己的训练记忆补全了。它对 RESTful API 的惯用法太熟悉所以会自动填上page_size这种“应该存在”的字段。解决Prompt 里的“严禁新增”约束只能降低概率不能杜绝。真正有效的是生成后校验。这里有个简单脚本用代码块中出现的标识符与接口字段做差集import re def find_hallucinated_params(doc_text: str, allowed: set) - set: candidates set(re.findall(r([a-zA-Z_][a-zA-Z0-9_]*), doc_text)) return candidates - allowed注意这个方法会误报——示例 JSON 里的字段也可能被反引号包裹。它的价值不是自动改文档而是把可疑字段列出来给人看。文档生成永远是辅助校验环节不能省。给模型喂输入时把允许出现的字段白名单写进 prompt 里也能明显减少幻觉我一般会在接口信息后面接一行允许出现的字段limit, offset, total, items。5.4 现象Markdown 代码块嵌套导致渲染崩坏现象最终生成的 PDF 里请求示例那段代码只显示了一行后面的 JSON 全变成了正文文字。原因这是最早踩的坑。一开始让模型直接输出 Markdown 片段模型在request_example里用了三个反引号。合并脚本把它们当成外层围栏的结束符后续文本全部错乱。解决永远不要让模型负责写 Markdown 围栏。改成 3.2 的结构化输出方式模型只返回 JSON 字符串里的纯内容由本地脚本负责拼装代码块。另一个兜底手段是生成完用text.count()检查反引号数量是否为偶数是奇数就说明有未闭合的围栏需要重新生成该接口。还有一个小坑即使模型按结构化 JSON 返回request_example字符串本身在 JSON 里也可能包含换行需要本地代码在拼 Markdown 时保持缩进和换行不变。否则代码块里所有行会粘连在一起JSON 格式没法看。用json.dumps(json.loads(section[request_example]), ensure_asciiFalse, indent2)做一次重排能解决。5.5 现象多个接口的文档风格不统一现象有的接口小节标题是“功能概述”有的变成“接口说明”有的参数表是 Markdown 表格有的已经写成列表。原因每个接口都独立调用一次模型模型没有上下文记忆所以每次都会自由发挥。Prompt 里写得再细也架不住模型对“概述”的处理方式不同。解决把风格样本写进 prompt先给一段你满意的旧文档片段再让模型“严格按照该风格输出”。同时把 temperature 固定在 0.2 以下。生成后跑一个简单统计脚本检查每个 section 是否包含五类固定标题缺了就重新生成。风格统一比内容正确更依赖流程约束不能靠人眼抽查。统计脚本不需要复杂逻辑几十行就够遍历所有生成片段把###标题抽出来跟期望的集合做差集输出差异百分比。我见过最夸张的一次同一批 30 个接口生成了 14 种“参数说明”标题写法加了风格样本之后直接收敛到 1 种。6. 进阶把文档生成从“一次性任务”变成“持续维护的常驻流水线”6.1 用 git diff 做文档质量回归全量生成的文档一旦落地下一步是让它在每次接口变更后自动更新。但这个“自动”必须有护栏否则模型在没人发现问题时把错误悄悄改进去。我的习惯是把生成的api-reference.md纳入 git 管理每次生成后先看 diff 再提交。git diff --unified0 -- api-reference.md | grep -E ^[-] | grep -vE ^(\\\|---)去掉和---后剩下的才是真正的内容增删。只看前 120 行足够判断这次改动是“字段描述微调”还是“整个文档重写”。如果是后者优先怀疑 prompt 被改坏或者输入范围发生了变化。这个动作就像给自动生成加了一道人工闸门成本很低但能拦住大部分质量问题。6.2 增量生成只重写变化的接口接口多的时候全量生成既费 token 又慢而且可能把之前人工修订过的那部分文档冲掉。增量生成的办法是用 git 看到本次变更涉及哪些 path只重新生成这些接口对应的 Markdown 片段。# 假设 openapi.yaml 是接口定义的唯一来源 changed_paths$(git diff HEAD~1 --name-only | grep -E openapi\.ya?ml$) # 交给脚本根据变更定位到接口路径 python renumber.py api-reference/docs --changed-openapi $changed_paths重点在于处理脚本只更新受影响的片段然后重新跑merge_sections。这样人工在旧文档上做的修正会被保留不会被同一段 prompt 反复生成覆盖掉。增量更新是自动文档系统能不能长期跑下去的关键全量重写每次都会烧掉大量 token效果却不稳定。6.3 接到 CI 或 cron 里最后一步是把整条链路交给定时任务或 CI。对独立开发者来说最简单的方案是 cron0 2 * * * cd /srv/docs ./build_pdf.sh git commit -am auto docs update git pushCI 方案更稳妥的地方在于 API Key 作为环境变量注入不外露在 shell 历史里而且每次更新能留一次构建记录PDF 出错也好回溯。但注意 cron 里直接跑git commit不是好习惯万一生成中断会留下坏提交。我的做法是先生成到临时目录diff 非空且没有语法错误后再 commit。现在这条文档生成链路已经成了每天都跑的常驻任务。每次打开 Git 记录看到“auto docs update”心里都踏实不少——至少不会再出现上线前一天发现文档里是旧字段的事了。所谓降维打击其实不是模型有多大本领而是你在流程里替它把坑填平了。希望帮到你。本文还有配套的精品资源点击获取