---

name: api-documentation description: API 文档生成工具。当用户需要生成 API 接口文档、维护接口规范、或进行前后端接口对接时使用。支持从前端或后端代码生成标准化的 API 文档。

API 文档生成

概述

本 Skill 用于生成和维护 API 接口文档，确保前后端开发的接口规范统一。适用于任何后端技术栈。

使用场景

• 前端开发完成后，生成 API 文档供后端参考
• 后端开发完成后，更新 API 文档供前端对接
• 前后端联调时的接口规范确认

---

API 文档生成提示词

从前端代码生成 API 文档

@api 根据当前文件下所有的 API 文件生成接口文档，放到 doc 目录中，遵循以下格式：

• 接口名称
• 功能描述: 详细描述接口的功能和用途
• 入参: 参数类型和说明
  - param1: type - 参数1说明
  - param2: type - 参数2说明
• 返回参数: 返回值类型和说明
  - field1: type - 字段1说明
  - field2: type - 字段2说明
• url地址: /api/endpoint
• 请求方式: GET/POST/PUT/DELETE

从后端代码生成 API 文档

@controller 根据当前控制器文件生成接口文档，包含：
- 接口名称和功能描述
- 请求方式和URL
- 请求参数（Query/Body/Path）
- 响应参数结构
- 错误码说明
- 示例请求和响应

---

API 文档格式标准

基本信息

## 接口名称

**接口名称：** 简短描述接口功能
**功能描述：** 详细描述接口的业务用途
**接口地址：** /api/v1/endpoint
**请求方式：** GET/POST/PUT/DELETE
**Content-Type：** application/json

请求参数

参数名	类型	必填	说明	示例值
page	int	否	页码（默认1）	2
pageSize	int	否	每页数量	20

响应格式

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

错误码说明

错误码	说明
200	成功
400	参数错误
401	未登录
403	无权限
404	资源不存在
500	服务器错误

---

接口规范约束

请求方式规范

方法	用途
GET	获取资源
POST	创建资源
PUT	更新资源
DELETE	删除资源

文档存放位置

• 项目文档目录: doc/api/ 或 docs/api/

文档命名规范

• 按模块命名: {模块名}-api.md
• 示例: user-api.md, order-api.md