doa-apidoclisted

# 接口说明文档生成 ## 工作流 ``` 用户提供需求/代码 → 确认输出格式(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](references/apidoc-pdf-template.py) - **Word**: 读取 [references/apidoc-word-template.py](references/apidoc-word-template.py) 基于模板生成定制化 Python 脚本，替换其中的内容数据。 ### 设计规范 #### 颜色体系（商务蓝主题，PDF/Word 通用） | 角色 | 色值 | 用途 | |------|------|------| | pri | `#1A365D` | 深蓝 - 主标题、表头、页眉线