API 문서 & 스펙

## 사용자 API

사용자를 생성하려면 POST 요청을 /api/users로 보내면 됩니다.
이름과 이메일이 필요하고, 이메일은 유효해야 합니다.
성공하면 201이 오고 실패하면 400이 옵니다.

# POST /api/users
summary: 사용자 생성
authentication: Bearer token (required)

request:
  body:
    name: string (required, 2-50자)
    email: string (required, 유효한 이메일)
    role: "admin" | "user" (optional, default: "user")

responses:
  201:
    body: { id, name, email, role, createdAt }
  400:
    - INVALID_EMAIL: 이메일 형식 오류
    - DUPLICATE_EMAIL: 이미 존재하는 이메일
    - NAME_TOO_SHORT: 이름 2자 미만
  401:
    - UNAUTHORIZED: 토큰 없음 또는 만료

example:
  request:
    POST /api/users
    Authorization: Bearer eyJ...
    { "name": "홍길동", "email": "hong@example.com" }
  response:
    201
    { "id": "usr_123", "name": "홍길동", "email": "hong@example.com", "role": "user" }

## [METHOD] [PATH]

**요약**: [한 줄 설명]
**인증**: [인증 방식] (required/optional)
**권한**: [필요한 역할/권한]

### 요청

| 파라미터 | 위치 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| [name] | body/query/path | [type] | [Y/N] | [설명] |

### 응답

**성공 (200/201)**
\`\`\`json
{
  "field": "value"
}
\`\`\`

**에러**
| 코드 | 에러 | 설명 |
|---|---|---|
| 400 | INVALID_INPUT | [설명] |
| 401 | UNAUTHORIZED | [설명] |
| 404 | NOT_FOUND | [설명] |

### 예시

\`\`\`bash
curl -X [METHOD] https://api.example.com[PATH] \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"field": "value"}'
\`\`\`

openapi: 3.0.3
info:
  title: Users API
  version: 2.3.0
paths:
  /api/users:
    get:
      summary: 사용자 목록 조회
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: role
          in: query
          schema: { type: string, enum: [admin, user] }
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/User' }
                  pagination:
                    $ref: '#/components/schemas/Pagination'

# GET /api/orders?status=pending&from=2026-01-01&page=2&limit=50
summary: 주문 목록 조회 (필터링 + 페이지네이션)

parameters:
  - status: string (optional) — pending | confirmed | shipped | delivered
  - from: date (optional) — 시작일 (ISO 8601)
  - to: date (optional) — 종료일 (ISO 8601)
  - page: integer (optional, default: 1)
  - limit: integer (optional, default: 20, max: 100)

response (200):
  data:
    - id: "ord_456"
      status: "pending"
      customer: { id: "usr_123", name: "홍길동" }  # 중첩 객체
      items:
        - product: { id: "prd_789", name: "키보드" }
          quantity: 2
          price: 89000
      total: 178000
      createdAt: "2026-03-20T10:30:00Z"
  pagination:
    page: 2
    limit: 50
    total: 347
    hasNext: true

## v2 변경사항 (v1 대비)

| 엔드포인트 | 변경 | v1 | v2 |
|---|---|---|---|
| GET /users | 응답 필드 추가 | - | `lastLoginAt` 추가 |
| POST /users | 필수 필드 변경 | email만 필수 | email + name 필수 |
| DELETE /users/:id | 동작 변경 | 즉시 삭제 | soft delete (30일 보관) |

## 인증

### 토큰 취득
POST /auth/login
Body: { "email": "...", "password": "..." }
Response: { "accessToken": "eyJ...", "refreshToken": "...", "expiresIn": 3600 }

### 토큰 사용
모든 API 요청에 헤더 포함:
Authorization: Bearer {accessToken}

### 토큰 갱신
POST /auth/refresh
Body: { "refreshToken": "..." }
Response: { "accessToken": "eyJ...", "expiresIn": 3600 }

### 에러
- 401 UNAUTHORIZED: 토큰 없음 또는 형식 오류
- 401 TOKEN_EXPIRED: 토큰 만료 → /auth/refresh 호출
- 403 FORBIDDEN: 권한 부족 (역할 확인)

다음 라우트 핸들러 코드를 분석해서 API 문서를 작성해줘.

포함할 내용:
1. 엔드포인트 요약 (METHOD, PATH, 인증, 한 줄 설명)
2. 요청 파라미터 표 (이름, 위치, 타입, 필수 여부, 설명)
3. 응답: 성공 + 에러 케이스 (코드, 에러명, 설명)
4. curl 예시

코드에서 직접 추출하고, 추측하지 마.