---

name: api-docs description: 按项目规范编写 API 文档。使用场景：用户要求写接口文档、补充 API 说明、为第三方或内部接口编写文档时。

API 文档（api-docs）

按 references/specification.md 编写 API 文档，保证格式统一、可供第三方或前端对接。

何时使用

• 撰写、补充或修订接口说明、对接文档
• 为第三方或内部调用方提供可实现的 API 描述

工作流程

1. 从路由与实现代码提取真实路径、参数名、类型与错误码，避免编造字段。
2. 遵守规范中的章节结构、表格列、Markdown 约束与「禁止省略」条款。
3. 版式与接口小节写法对照 references/examples.md；若为已有文档增量编辑，保持与既有小节风格一致。

增量更新必检规则

1. 修改文档时，将更新日期同步为当天，创建日期保持不变。
2. 接口契约或业务规则变化时，按项目约定升版；同一批尚未交付的修改合并记录，避免每次编辑都升版。
3. 修改记录注明涉及的接口、字段、行为及兼容性变化。
4. 交付前核对：头部版本＝最新修改记录版本，更新时间正确，参数表与所有 JSON 示例一致。 逐一检查请求、成功和失败示例，包括嵌套字段、类型、必填性、默认值与枚举值，避免遗漏其他位置的同类示例。
5. 纯错字或排版修正可不升版，但仍更新日期，并在当前版本的修改记录中注明修正。

参考文件

• references/specification.md — 章节结构、参数表约定与禁止省略规则
• references/examples.md — 虚构「图书管理系统」完整示例