用大模型API自动生成接口文档：零基础配置与避坑
如果你希望把代码里的接口注释自动变成可读的 API 文档，用大模型 API 生成是一个省时省力的办法。
这篇教程会从零开始，带你完成环境准备、脚本编写、文档输出和常见报错处理，每一步都给出可执行的命令和配置示例。
先确认你的使用场景和前提条件
大模型 API 文档生成适合以下情况：你已经有结构化的接口定义（比如 OpenAPI 规范、代码注释或数据库表结构），希望通过大模型整理成自然语言说明、示例请求和参数表格。
如果接口定义本身缺失或不完整，生成质量会明显下降。
开始前需要准备：
- 一个可用的大模型 API 账号（如 OpenAI、DeepSeek、通义千问等），并获取 API Key。
- 一台能访问外网的 Linux 或 macOS 开发机，Windows 可用 WSL。
- Python 3.8 以上环境，建议使用虚拟环境隔离依赖。
- 你的接口定义文件，例如
openapi.json或代码中的注释片段。
注意：不同厂商的 API 地址和模型名称不同，请以你所用平台的官方文档为准。本文以兼容 OpenAI 接口格式的服务为例，替换base_url和model即可适配其他平台。
配置 API 环境并安装依赖
先创建项目目录并安装 Python 依赖。
打开终端执行：
mkdir llm-doc-gen && cd llm-doc-gen
python3 -m venv venv
source venv/bin/activate
pip install openai把 API Key 写入环境变量，避免硬编码在脚本里：
export LLM_API_KEY="你的API密钥"
export LLM_BASE_URL="https://api.openai.com/v1"
export LLM_MODEL="gpt-4o-mini"如果你使用的是其他兼容服务，把 LLM_BASE_URL 换成对应的接口地址，LLM_MODEL 换成平台支持的模型名。
执行 echo $LLM_API_KEY 应能输出密钥，说明环境变量生效。
编写生成脚本：从接口定义到 Markdown 文档
下面是一个最小可用的 Python 脚本 generate_doc.py，它读取 openapi.json，调用大模型生成 Markdown 格式的接口说明。
import os, json
from openai import OpenAI
client = OpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ.get("LLM_BASE_URL")
)
with open("openapi.json", "r", encoding="utf-8") as f:
api_spec = f.read()
prompt = f"""你是一名技术文档工程师。请根据以下 OpenAPI 定义，生成一份 Markdown 格式的 API 文档。
要求：
1. 按接口路径分组，每个接口包含功能说明、请求方法、参数表格、请求示例和响应示例。
2. 参数表格包含字段名、类型、是否必填、说明。
3. 语言简洁，面向零基础开发者。
接口定义：
{api_spec[:6000]}
"""
response = client.chat.completions.create(
model=os.environ["LLM_MODEL"],
messages=[{"role": "user", "content": prompt}],
temperature=0.3
)
doc = response.choices[0].message.content
with open("api_doc.md", "w", encoding="utf-8") as f:
f.write(doc)
print("文档已生成：api_doc.md")保存后运行 python generate_doc.py，如果终端输出“文档已生成”，并且当前目录出现 api_doc.md，说明调用成功。
打开文件检查内容是否包含接口路径、参数表格和示例。
关键点：接口定义过长时不要一次性全部塞进 prompt。
可以按路径分组循环调用，每次只传一个接口的定义，避免超出模型上下文限制。
常见报错与避坑指南
实际执行时容易遇到以下几类问题：
- 401 未授权：检查
LLM_API_KEY是否设置正确，环境变量是否在当前终端生效。可以打印os.environ.get("LLM_API_KEY")的前几位确认。 - 404 或模型不存在：核对
LLM_BASE_URL是否包含/v1，以及LLM_MODEL是否拼写正确。 - 超时或连接失败：确认服务器能访问外网，必要时设置代理。可以在脚本中给
OpenAI客户端增加timeout=30参数。 - 生成内容截断：模型输出有最大 token 限制。把接口定义拆小，或者让模型只生成摘要和参数表格，示例部分单独生成。
- 格式不符合预期：在 prompt 中明确要求“只输出 Markdown，不要额外解释”，并降低
temperature到 0.2 左右。
另外，不要把 API Key 提交到 Git 仓库。
建议使用 .env 文件配合 python-dotenv 加载，并在 .gitignore 中排除 .env。
验证生成效果并集成到项目
生成文档后，从三个方面检查质量：
- 完整性：每个接口是否都有功能说明、参数表格和示例。
- 准确性：参数类型和必填项是否与
openapi.json一致，可以随机抽查两个接口对照原始定义。 - 可读性：零基础开发者能否看懂字段含义，示例中的请求地址和参数是否合理。
如果文档需要持续更新，可以把脚本接入 CI 流程，在接口定义变更后自动重新生成。
例如在 GitLab CI 中添加一个 job，运行 python generate_doc.py 并提交 api_doc.md。
注意设置 API Key 为 CI 变量，不要写在配置文件中。
对于团队使用，建议先在本地跑通完整流程，再考虑自动化。
生成结果需要人工抽查，不能完全替代人工审核。
两个常见疑问
生成文档时提示上下文超长怎么办？
把接口定义按路径拆分成多个小文件，循环调用模型，每次只传一个接口的定义。
也可以先让模型生成接口列表摘要，再逐条生成详细文档。
没有 OpenAPI 文件，只有代码注释能生成吗？
可以。
把代码注释片段作为输入传给模型，并在 prompt 中说明注释的格式。
但注释本身需要包含参数名、类型和说明，否则生成内容会不完整。
建议先整理注释，再调用模型。
按照以上步骤操作，你可以在半小时内跑通大模型 API 文档生成的基本流程。
遇到报错时优先检查 API Key、接口地址和模型名称这三个配置项，大部分问题都能快速定位。
