Gemini API文档自动生成：标准Markdown格式输出实战教程
当通过Gemini API自动生成可直接交付的产品文档时，经常出现Markdown结构混乱的问题——标题层级错位、表格对不齐、代码块缩进丢失，导致每次需要手动修复格式超过30分钟才能发给产品与前端团队。根本原因并非模型能力不足，而是输入数据与约束条件的粒度不够精细。以下方法经过多个生产项目验证，能够一次性输出符合交付标准的文档内容。
构建结构化输入数据
确保Gemini能够准确解析接口事实。避免直接输入原始日志或模糊的业务描述，应整理三类明确输入：
① 接口事实层：导出完整的OpenAPI 3.0 JSON文件（路径、参数schema、响应状态码必须完备）；【缺失200/400/500状态码定义会导致错误码表空白】
② 语义层：提供Confluence链接或纯文本段落，明确模块目标用户、核心业务目标及字段别名（例如“user_id”在前端称为“用户唯一标识”）；
③ 约束层：以单句明确输出规范：“仅使用标准Markdown语法，#表示一级标题，##表示二级标题，###表示三级标题，代码块必须用```lang包裹，表格必须用|分隔且首行包含分隔线。”
设计强约束提示词
方法一：嵌套锚点法（适用于首次生成）
在提示词开头插入带标签的占位结构，示例如下：
# [产品名称] API 文档
## [接口功能简述]
### 请求地址
- HTTP方法：
- URL：
### 请求参数
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| | | | |
末尾追加指令：“严格复现上述结构，所有标题使用#号标记，表格必须包含分隔线，代码块必须用```包裹，不添加任何额外解释性文字。”
方法二：XML指令法（适用于调整已有初稿）
将Gemini已生成的混乱内容复制进来，添加前缀：“将以下内容转换为标准Markdown：所有‘第一章’改为‘# ’，所有‘1.’改为‘### ’，所有无序列表项前加‘- ’并顶格，所有代码片段用```python或```json包裹，所有表格补全|---|分隔行。”
调用Gemini 1.5 Pro并校验输出
使用新版google-genai SDK初始化模型：
from google import genai
model = genai.GenerativeModel("gemini-1.5-pro")
传入拼接后的提示词（事实层+语义层+约束层），设置temperature=0.2以降低随机性；
获取response.text后，立即执行三步校验：
① grep -c "^#" 检查一级标题是否唯一；
② 检查是否存在未闭合的```（即```出现奇数次）；
③ 使用pandoc -f markdown -t html --standalone测试能否无报错转换为HTML——失败则表明Markdown语法存在硬伤。
若校验失败，无需重试，直接提取出错段落，单独构造新提示：“修正以下表格：补全第二行分隔符，对齐第三列内容，删除多余空格。”
批量注入与版本固化
将校验通过的Markdown文档存入Git仓库，路径为docs/api/v1.2.0/product.md；
在CI流水线中配置GitHub Action：当OpenAPI JSON更新时，自动触发Gemini重生成→执行校验脚本→diff比对→仅在结构一致且新增字段被覆盖时允许合并；
每次发布新版本文档，同步更新文档页脚：“生成时间：2026-06-02 | 依据OpenAPI SHA：a7f3b9e”。