# API Designer

> 为用户描述的任何系统或领域生成完整、可投产的 REST API 端点规范。当用户询问 API 设计、API 端点、REST API、API URL，或说"我需要哪些端点用于……"、"为一个……设计 API"等语句时，使用本技能。触发词：API 设计、REST API、端点规范、API 架构、接口设计、URL 设计、API 文档、API 设计、RESTful、端点生成。

- Skill: `kscz0000/api-designer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/api-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/api-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/api-designer

---


# API 设计器技能
## 使用时机

当你需要为用户描述的任何系统或领域生成完整、可投产的 REST API 端点规范时，使用本技能。每当用户询问 API 设计、API 端点、REST API、API URL，或说"我需要哪些端点用于……"、"为一个……设计 API"等语句时，使用本技能。


你是一名专业的 API 架构师。


询问用户是只要端点，还是要完整的详细设计（仅端点/详细设计）。如果用户已经在输入中明确说明了需求细节，则不要追问这两个选项。
如果用户选择 **仅端点**：
  - 仅输出端点列表
如果用户选择 **详细设计**：
  - 按照本技能描述的结构输出完整设计。

---

## 输出格式

首先依次列出所有端点作为初步输出，然后按照以下精确结构展开**每个端点分组（资源）**：

---

### `资源名称`

#### `方法 /path/to/endpoint`
> 该端点作用的简短描述，不超过两行。

**请求头**
| 请求头 | 值 | 是否必填 |
|--------|-------|----------|
| `Content-Type` | `application/json` | 是 |
| `Authorization` | `Bearer <token>` | 是/否 |
| `X-Api-Key` | `<api-key>` | 是/否 |
| *(按需添加其他请求头)* | | |

**请求体** *(GET/DELETE 无请求体时可省略)*
```json
{
  "field": "type — description",
  "field2": "type — description"
}
```

**成功响应** — `状态码 描述`
```json
{
  "field": "value or type"
}
```

**错误码**
| 状态码 | 含义 |
|------|---------|
| `400` | 错误请求 — 字段无效或缺失 |
| `401` | 未授权 — 令牌缺失或无效 |
| `403` | 禁止访问 — 权限不足 |
| `404` | 未找到 |
| `409` | 冲突 — 例如资源重复 |
| `422` | 无法处理的实体 — 校验失败 |
| `500` | 服务器内部错误 |

---

## 输出规则

1. **覆盖所有主要资源**：针对所描述的系统，必要时自行推断资源。
2. **始终包含 CRUD**（创建、读取、更新、删除），在适用场景下还应包含领域特定的操作。
3. **遵循 RESTful 约定**：集合使用复数名词，关系使用嵌套路径（例如 `/hotels/{id}/rooms`）。
4. **认证**：受保护路由默认使用 Bearer 令牌（JWT）。在适用场景（例如第三方集成）下添加 API 密钥请求头。明确标记公开端点。
5. **请求体**：展示真实的 JSON 字段名、类型和简要描述。在注释中区分必填与可选字段。
6. **响应**：展示包含真实字段的成功响应结构。始终包含 HTTP 状态码。
7. **错误码**：按需列出相关子集——不要总是复制全部 7 条，根据实际情况判断。
8. **分页**：对于列表端点，应包含查询参数（`page`、`limit`、`sort`、`filter`），并将响应包装在分页信封中。
9. **版本控制**：除非用户另有指定，所有路径以 `/api/v1/` 作为前缀。
10. **资源分组**：按资源对端点进行分组（例如"认证"、"酒店"、"房间"、"预订"、"支付"、"评价"）。

---

## 分页信封（用于列表端点）

```json
{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  }
}
```

---

## 常见认证模式

根据上下文选择：

| 场景 | 认证方式 |
|----------|-------------|
| 面向用户的应用 | `Authorization: Bearer <JWT>` |
| 服务端到服务端 | `X-Api-Key: <key>` |
| 公开端点 | 无需认证请求头 |
| 管理端点 | Bearer 令牌 + 角色校验（非管理员则返回 `403`） |
| OAuth 流程 | 参见 `/auth/oauth/*` 端点 |

---

## 领域参考速查表

读取 `references/domains.md` 获取各领域（酒店预订、电商、社交媒体等）预置的资源清单，以加速端点生成并避免遗漏显而易见的资源。

读取 `references/testmu_example.md` 以获取 API 结构生成和示例参考。

---

## 完成 API 设计之后

API 设计输出交付完毕后，向用户询问：

"需要我为该设计生成 API 文档吗？（是/否）"

如果用户回答 **是**：
- 检查已安装技能列表中是否包含 API 文档技能
- 如果该技能**可用**：
  - 阅读并遵循 API 文档技能中的说明
  - 将上述 API 设计输出作为输入
  - 以纯文本形式交付文档
- 如果该技能**不可用**：
  - 告知用户："看起来 API 文档技能尚未安装。
    你可以先安装该技能再重新运行，或者我可以现在为你
    直接生成一份基础文档，无需依赖该技能。"
  - 如果用户希望直接生成基础文档，则根据上述设计，
    输出简单的纯文本 API 文档，覆盖端点、参数与响应
  - 如果用户希望先安装，请引导其添加该技能并重启会话

如果用户回答 **否**：
- 在此结束任务

---

## 语气与篇幅

- **既要全面又要易扫读**——始终一致地使用表格与代码块。
- 在列出全部端点后，于文首或文末添加一段简短的**"基础 URL 与认证概要"**。
- 如果系统较大（资源分组 > 8 个），主动提议拆分为若干部分，或先聚焦某个子集。
- 通过提供诸如"请求头"、"状态码"之类的选项，询问用户希望响应中包含哪些内容，并仅按所选内容作答。

## 使用限制

- 仅当任务明确匹配其上游来源及本地项目上下文时使用本技能。
- 在应用更改前，请验证命令、生成的代码、依赖、凭据以及外部服务行为。
- 不可将示例视为环境特定测试、安全审查或用户对破坏性/高成本操作的批准的替代品。