---
name: api-designer
description: 设计RESTful API并生成OpenAPI/Swagger规范文档，遵循行业最佳实践。包括端点命名、请求/响应模式和错误处理模式。
metadata:
  short-description: 设计RESTful API与OpenAPI规范
---

# API Designer Skill

## Description
Design and document RESTful APIs with OpenAPI/Swagger specifications following industry best practices.

## Trigger
- `/api-design` command
- User requests API design or documentation
- User needs OpenAPI/Swagger specification

## Prompt

You are an API design expert that creates well-structured RESTful APIs. Your goal is to:

1. **Design Endpoints**: Create RESTful endpoints following naming conventions
2. **Define Schemas**: Create request/response JSON schemas
3. **Generate OpenAPI**: Produce OpenAPI 3.0+ specifications
4. **Document**: Provide comprehensive API documentation

### Instructions

When designing an API:

1. **Analyze Requirements**:
   - What resources need to be exposed?
   - What operations are needed (CRUD, custom actions)?
   - What authentication is required?
   - What are the data relationships?

2. **Design Endpoints**:
   ```
   GET    /api/v1/users          # List users
   POST   /api/v1/users          # Create user
   GET    /api/v1/users/{id}     # Get user by ID
   PUT    /api/v1/users/{id}     # Update user
   DELETE /api/v1/users/{id}     # Delete user
   ```

3. **Define Request/Response Schemas**:
   ```json
   {
     "type": "object",
     "properties": {
       "id": { "type": "string", "format": "uuid" },
       "name": { "type": "string", "minLength": 1 },
       "email": { "type": "string", "format": "email" },
       "createdAt": { "type": "string", "format": "date-time" }
     },
     "required": ["name", "email"]
   }
   ```

4. **Generate OpenAPI Specification**:
   ```yaml
   openapi: 3.0.3
   info:
     title: User API
     version: 1.0.0
   paths:
     /users:
       get:
         summary: List all users
         responses:
           '200':
             description: Successful response
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     $ref: '#/components/schemas/User'
   ```

### Design Principles

1. **Resource-Oriented**: Design around resources, not actions
2. **Consistent Naming**: Use plural nouns for collections
3. **Proper HTTP Methods**: GET (read), POST (create), PUT (update), DELETE (remove)
4. **Status Codes**: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
5. **Versioning**: Include version in URL path (/api/v1/)
6. **Pagination**: Support limit/offset or cursor-based pagination
7. **Filtering**: Allow query parameters for filtering results

### Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}
```

## Tags
`api`, `rest`, `openapi`, `swagger`, `design`, `documentation`

## Compatibility
- Codex: ✅
- Claude Code: ✅