Doa apidoc

接口说明文档生成

工作流

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

Step 0: 确认输出格式

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

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

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

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

文档元信息（封面）

字段	说明
文档标题	如「接口说明文档」
副标题	项目名 + 文档类型描述
文档版本	V1.0
编制方	默认「{vendor_name}」，用户可覆盖
接收方	文档接收方
编制日期	日期
文档状态	初版发布 / 评审中 / 定稿

标准章节结构

章节	内容要求
一、接口总览	接口清单表格（#/名称/Method/Path/描述）+ 调用链路（ASCII 时序图）
二、公共约定	协议、Base URL、鉴权方式、数据格式、公共响应结构、错误码表
三、接口详细定义	每个接口：调用场景 + 请求头 + 入参表 + 入参示例 + 出参表 + 出参示例 + 错误场景
四、调用时序总结	汇总表（步骤/调用方/接口/触发条件/备注）

每个接口的标准子节

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 通用）

角色	色值	用途
pri	#1A365D	深蓝 - 主标题、表头、页眉线
sec	#2B6CB0	中蓝 - 章节标题(h2)
acc	#3182CE	亮蓝 - 小节标题(h3)、强调
lbg	#EBF4FF	浅蓝背景 - 信息卡片、首列
lgray	#F7FAFC	极浅灰 - 交替行
border	#CBD5E0	边框灰
txt	#2D3748	正文色
sub	#718096	辅助文字、页眉页脚
green	#276749	成功/通过
orange	#C05621	警告/待确认
red	#C53030	紧急/重要

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 让表头在跨页时重复显示