API 文档生成与维护

API 文档不是写一次就完了——接口在变、参数在变、返回值在变，文档却经常滞后于代码。这个案例展示如何用 LanMate 从代码中提取接口定义，生成结构化 API 文档，并在接口变更时同步更新变更说明。

用到的技能

• 内置技能（随 LanMate 安装，开箱即用）：Word 文档（lanmate-docx）、HTML 报告（lanmate-html-report）
• 技能商店：技术文档写作——指导技术内容的结构设计、代码示例编写和受众适配；Markdown 转换器——Markdown 与 HTML 双向转换，支持表格、代码块等语法

场景痛点

• 文档和代码脱节：接口改了但文档没更新，调用方踩坑才知道
• 接口定义散落各处：路由、参数、返回值要翻多个文件才能拼全
• 变更没有记录：哪个版本加了参数、哪个版本废弃了接口，全靠口口相传
• 调用示例缺失：只有接口签名，没有可复制的请求 / 响应示例

推荐流程

提示词示例

提取接口定义

请读取 src/ 目录下的代码文件，提取所有 API 接口定义，整理为表格：
- 接口名称和功能描述
- 请求路径和方法（GET / POST / PUT / DELETE）
- 请求参数（名称、类型、是否必填、说明）
- 返回值结构（字段名、类型、说明）
- 鉴权方式（Token / API Key / 无）
- 错误码及含义

读取代码中的接口定义、注释和类型声明来提取信息。
代码中未注释的功能描述，根据接口逻辑推断并标注"（推断）"。
输出 Word 接口清单。

生成 API 文档

请根据提取的接口定义，生成一份完整的 API 文档，每个接口包含：
1. 接口概述：功能说明和适用场景
2. 请求格式：路径、方法、请求头、请求参数表格
3. 请求示例：可复制的完整请求（含真实参数值）
4. 响应格式：返回值结构表格
5. 响应示例：成功和失败两种响应
6. 错误码表：错误码、含义、处理建议

请求示例中的参数值使用合理的示例数据，不要用 "xxx" 或 "test" 占位。
输出自包含 HTML 文档。

接口变更对比

请对比 src/ 目录（当前版本）和 src-v1/ 目录（上一版本）的代码，
识别 API 接口变更并分类：
- 新增接口：新出现的接口路径
- 修改接口：参数、返回值或行为有变化的接口
- 废弃接口：已删除或标记为废弃的接口

每个变更输出：
- 接口名称和路径
- 变更类型（新增 / 修改 / 废弃）
- 变更详情（改了什么）
- 影响范围（哪些调用方可能受影响）
- 迁移建议（修改类接口需要怎么适配）

无法从代码差异确定影响范围的，标注"待确认"，不要自行推测。
输出 HTML 变更报告。

生成变更日志

请根据接口变更对比结果，生成一份变更日志，包含：
- 版本号和发布日期
- 变更摘要（新增 N 个接口、修改 M 个接口、废弃 K 个接口）
- 逐条变更记录（接口、变更类型、详情、迁移建议）
- 不兼容变更标记（需调用方立即适配的变更置顶）

废弃接口需标注预计下线时间，代码中未标注的写"待确认"。
输出 Markdown 变更日志，再用 Markdown 转换器输出 HTML 版本。

验收标准

• 提取的接口定义与代码一致，推断内容有标注
• API 文档每个接口含请求示例和响应示例，示例参数值合理可验证
• 变更对比覆盖所有接口变更，分类准确
• 变更日志含迁移建议，不兼容变更置顶
• 废弃接口标注预计下线时间，未标注的写“待确认”

常见错误