接口说明文档生成

工作流

用户提供需求/代码 → 确认输出格式(PDF/Word/Both) → AI 结构化整理 → 生成 Python 脚本 → 运行输出文档

Step 0: 确认输出格式

必须在生成前使用 `vscode_askQuestions` 确认：

问题: 文档输出格式
选项:
  - PDF（适合交付/归档）  ← recommended
  - Word（适合后续编辑）
  - 都要

Step 1: 收集与整理接口信息

从用户提供的需求描述、后端代码、或接口定义中，提取并结构化为以下标准章节：

文档元信息（封面）

标准章节结构

每个接口的标准子节

3.x  {METHOD} {path} — {接口名}
  ├─ 调用场景（ColorBox 高亮）
  ├─ 请求头（如需鉴权）
  ├─ 入参（表格：参数/类型/必填/说明）
  ├─ 入参示例（code_block）
  ├─ 出参（表格：参数/类型/说明）
  ├─ 出参示例 — 成功 / 失败 / 各状态（code_block）
  └─ 错误场景（表格：code/场景）

内容整理原则

• 从代码/需求中推导完整的入参出参，字段名用 camelCase
• 必填字段标记 ✅
• 嵌套对象用 parent[].child 格式展示
• 枚举值列出全部可选项及含义
• 错误码覆盖 400/401/404/422/500 等常见场景
• 示例 JSON 使用真实可读的模拟数据

Step 2: 生成文档脚本

根据用户选择的格式，读取对应模板：

• PDF: 读取 references/apidoc-pdf-template.py
• Word: 读取 references/apidoc-word-template.py

基于模板生成定制化 Python 脚本，替换其中的内容数据。

设计规范

#### 颜色体系（商务蓝主题，PDF/Word 通用）

#### PDF 核心组件

模板提供以下 Flowable 组件：

• `SectionBar(text, color)` — 带色块的章节标题栏（白字 + 圆角深蓝底）
• `InfoCard(rows)` — 信息卡片（浅蓝底 + 边框，用于封面元信息）
• `Divider()` — 分隔线
• `ColorBox(text, bg, bc)` — 调用场景高亮框（浅蓝底 + 蓝色边框）
• `make_table(headers, rows, col_widths)` — 标准数据表格（深蓝表头 + 交替行）
• `make_kv_table(rows)` — 键值表格（左列浅蓝底粗体 + 右列正文）
• `code_block(text)` — 代码块（浅灰底 + 蓝色等宽字体）

#### Word 核心组件

模板提供以下函数：

• `add_section_bar(doc, text, color)` — 带色块的章节标题栏
• `add_info_card(doc, rows)` — 信息卡片
• `add_divider(doc)` — 分隔线
• `add_color_box(doc, text)` — 调用场景高亮框
• `add_table(doc, headers, rows, col_widths_mm)` — 标准数据表格
• `add_kv_table(doc, rows)` — 键值表格
• `add_code_block(doc, text)` — 代码块
• `add_paragraph(doc, text, ...)` — 段落（支持 <b> 标记）

#### 页眉页脚

根据实际项目名调整：

• 页眉左：{项目名} · {文档类型}
• 页眉右：CONFIDENTIAL 机密（可选）
• 页脚左：{vendor_name}（默认，用户可覆盖）
• 页脚右：第 X 页（PDF）/ 页码请在 Word 中查看（Word）

Step 3: 运行生成

输出目录：output/{项目名称}-接口文档/（每次新任务创建独立子文件夹）

PDF:

pip install reportlab
python generate_api_doc.py

Word:

pip install python-docx
python generate_api_doc_word.py

确认文档输出后告知用户文件路径。

注意事项

• PDF 字体注册使用 register_fonts() 函数，自动适配 Windows/macOS/Linux
• A4 纸张，左右上下边距 20mm
• 每个接口详细定义前使用 PageBreak()（PDF）或 doc.add_page_break()（Word）分页
• 表格列宽之和应为 ~166mm（PDF）/ 对应 Mm 值（Word），确保不溢出
• 代码块使用等宽字体：PDF 用 CF 蓝色 7.8pt，Word 用 Consolas 8.5pt
• Word 生成的 .docx 文件体积小、可继续编辑，适合需要后续调整的场景
• PDF 使用 repeatRows=1 让表头在跨页时重复显示