SkillHub

api-design-doc

v1.0.0

标准化API接口设计文档生成工具。根据需求文档、数据库DDL等输入，进行API的标准化、规范化设计，输出完整的API接口设计文档，包括错误码规范、接口格式规范、入参出参定义、JSON示例等，指导后续的代码开发和前后端联调。使用场景包括：(1) 根据业务需求设计RESTful API接口，(2) 基于数据库DDL生成对应的CRUD接口文档，(3) 规范化现有API接口文档，(4) 为前后端联调提供标准化的接口规范文档

Sourced from ClawHub, Authored by cnsunxuefeng

Installation

Please help me install the skill `api-design-doc` from SkillHub official store. npx skills add cnsunxuefeng/api-design-doc

API Design Doc

根据需求文档、数据库DDL等输入，生成标准化的API接口设计文档。

工作流程

  1. 收集输入信息
  2. 获取需求文档或业务需求描述
  3. 获取数据库DDL（如果适用）

  4. 明确接口的业务场景和功能需求

  5. 页面功能与API接口关系

  6. 明确页面功能与API接口的对应关系

  7. 设计API接口

  8. 确定接口的RESTful风格（GET/POST/PUT/DELETE）
  9. 定义接口URL路径
  10. 设计入参和出参结构

  11. 选择合适的错误码

  12. 生成接口文档

  13. 使用标准模板生成每个接口的详细文档

  14. 包含功能描述、入参、出参、URL、请求方式、JSON示例

  15. 输出完整文档

  16. 页面功能与API接口关系
  17. 汇总所有接口文档
  18. 包含错误码规范总表
  19. 提供接口格式规范说明

参考资料

错误码规范

参见 error-codes.md - 完整的错误码列表和说明

接口文档模板

参见 api-spec-template.md - 标准的API接口文档格式

命名规范

参见 naming-conventions.md - API命名和参数命名规范

最佳实践

参见 best-practices.md - API设计最佳实践

模板文件

API文档模板

使用 templates/api-doc-template.md 作为单个接口文档的模板

API响应模板

使用 templates/api-response-template.json 作为标准响应格式参考

使用指南

当用户请求设计API接口时：

  1. 首先读取 error-codes.md 了解错误码规范
  2. 根据业务需求设计接口，参考 best-practices.md
  3. 使用 api-spec-template.md 的格式生成每个接口文档
  4. 确保命名符合 naming-conventions.md 的规范
  5. 输出完整的API设计文档，包含所有接口和错误码总表

输出格式

接口文档必须包含以下部分：

  1. 错误码规范总表
  2. 接口格式规范说明
  3. 页面功能与API接口关系表，包含以下内容：
  4. 页面名称：前端页面或功能模块的名称
  5. 页面功能描述：页面或功能模块的简要说明
  6. 关联API接口：该页面调用的API接口列表（API-Id）
  7. 操作类型：GET/POST/PUT/DELETE等HTTP方法
  8. 接口URL：完整的API路径

  9. 接口清单与详细定义，详细定义的规范如下：

  10. 接口编号（API-Id）：顺序生成，格式为 API001-接口名称，如 API001-用户登录, API002-获取用户列表, ...

  11. 功能描述：详细描述接口的功能和用途
  12. 入参：参数类型和说明（标注必填/可选）
  13. 返回参数：返回值类型和说明
  14. URL地址：完整的API路径
  15. 请求方式：GET/POST/PUT/DELETE
  16. 接口 JSON 示例：完整的请求和响应JSON示例

输出位置

  • 仅生成一份API文档，保存在项目根目录下的 doc/ 目录。
  • 若 doc/ 目录不存在，应自动创建该目录后再写入文档。
  • 文档文件名固定为：API接口设计文档.md，内容包含：
  • 错误码总表（来自 references/error-codes.md）
  • 接口格式规范（来自 references/api-spec-template.md 的说明部分）
  • 页面功能与API接口关系表（按页面或功能模块归类）
  • 接口清单与详细定义（按模块归类的所有接口条目）