API 문서 & 스펙

## 사용자 API

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

openapi: 3.2.0
info:
  title: Users API
  version: 2.3.0
paths:
  /api/users:
    post:
      operationId: createUser
      summary: 사용자 생성
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              valid:
                value: { "name": "Hong", "email": "hong@example.com" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

api-contract/
├── openapi.yaml
├── errors.md
├── auth.md
├── rate-limits.md
├── idempotency.md
├── examples/
│   ├── create-user.request.json
│   └── create-user.response.json
└── validation.md

paths:
  /api/events:
    get:
      operationId: streamEvents
      responses:
        '200':
          description: Server-sent event stream
          content:
            text/event-stream:
              schema:
                type: string

{
  "name": "create_user",
  "description": "Create a user account.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "minLength": 2 },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["name", "email"]
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": true
  }
}

## 인증

### 토큰 취득
- Endpoint: `POST /auth/token`
- Grant: `client_credentials`
- Scope: `users:write`
- Expiry: 3600 seconds

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

### 에러
| HTTP | code | 의미 | 복구 |
|---|---|---|---|
| 401 | TOKEN_EXPIRED | 토큰 만료 | 새 토큰 발급 |
| 403 | INSUFFICIENT_SCOPE | scope 부족 | `users:write` 요청 |
| 429 | RATE_LIMITED | 요청 제한 | `Retry-After` 이후 재시도 |

pnpm openapi:lint
pnpm openapi:diff --from main --to HEAD
pnpm test:contract

다음 route handler와 OpenAPI 파일만 근거로 API 문서를 갱신해줘.

포함할 내용:
1. operationId, method, path, 인증, scope
2. request/response schema와 예시
3. error code와 recovery action
4. idempotency, rate limit, retry 정책
5. MCP Tool로 노출할 경우 inputSchema/outputSchema와 annotation 제안
6. breaking change 여부와 검증 명령

금지:
- 코드나 스펙에 없는 파라미터를 만들지 않는다.
- 최신 OpenAPI 버전을 추정하지 않는다.
- tool annotation을 보안 보장으로 표현하지 않는다.