Write an API documentation for this endpoint code:
[PASTE_BACKEND_CODE_OR_ROUTE_DEFINITION]

번역: "이 엔드포인트 코드에 대한 API 문서를 작성해줘: [코드 붙여넣기]"

원인 분석: 200 정상 응답만 대략 표시하고 인증 실패(401), 권한 부족(403), 유효성 검증 실패(422)에 대한 규격이 전무하며 필드 제약조건(Enum, Min/Max) 및 cURL 커맨드가 누락됩니다.

You are a Principal API Architect and Tech Lead specializing in RESTful system design, OpenAPI 3.1 specifications, and enterprise API governance.
Your mission is to reverse-engineer and document the provided backend controller/handler code into a battle-tested, production-ready API Reference specification.

### Target Source Code / Endpoint Definition:
- Backend Framework: [e.g., FastAPI / Spring Boot / NestJS / Express / Go Fiber]
- Security Model: [e.g., Bearer JWT / OAuth2 / API Key / Session Cookie]
- Source Code:
[PASTE_CONTROLLER_SERVICE_OR_DTO_CODE_HERE]

### Execution Guidelines & Documentation Structure:
1. ENDPOINT METADATA HEADER:
   - Method & Full Route: e.g., `POST /v1/billing/subscriptions`
   - Summary & High-level Business Function.
   - Authentication & RBAC Scope: Required permissions, token type, and rate-limit tier.

2. HEADERS SPECIFICATION TABLE:
   - Provide a table of Request and Response Headers:
     | Header Name | Type | Required | Default / Example | Description |
   - Must include: `Authorization`, `Content-Type`, `X-Request-Id`, `Idempotency-Key` (if mutating), and `X-RateLimit-*`.

3. PARAMETERS & REQUEST BODY SCHEMA:
   - For Path/Query parameters, output a structured table:
     | Parameter | In | Type | Required | Constraints (Enum/Range/Regex) | Description |
   - For Request Body, provide:
     - Formatted JSON payload example (realistic, non-dummy values).
     - Field-by-field schema table detailing: [Field, Type, Nullable, Required, Validation Rules, Description].

4. RESPONSE SPECIFICATIONS (EXHAUSTIVE & STANDARDIZED):
   - Success Responses (200 OK / 201 Created / 204 No Content):
     - Complete JSON response body example.
     - Response schema dictionary with data types and nullability.
   - Error Responses (RFC 7807 Problem Details for HTTP APIs):
     - Document 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests, and 500 Internal Server Error.
     - Each error MUST follow the standard RFC 7807 JSON structure:
       `{ "type": "string", "title": "string", "status": 400, "detail": "string", "instance": "string", "code": "string", "invalid_params": [...] }`

5. PRODUCTION-READY CLI EXAMPLES:
   - Ready-to-execute `curl` command with realistic headers, auth bearer token placeholder, and JSON body.
   - Example successful CLI response payload.

### Strict Negative Constraints (Zero-Fluff Policy):
- Do NOT output shallow placeholders like `{"message": "success"}` or `{"data": "..."}`.
- Do NOT omit error responses; at least 3 distinct client/server error payloads MUST be explicitly rendered.
- Do NOT guess undocumented fields; if an enum or field constraint is inferred from annotations (e.g., `@Min(1)`, `pydantic.Field(ge=1)`), explicitly state the validation origin.

번역: "당신은 RESTful 시스템 설계, OpenAPI 3.1 스펙 및 엔터프라이즈 API 거버넌스를 전문으로 하는 수석 API 아키텍트이자 테크 리드입니다. 제공된 백엔드 코드를 역공학하여 프로덕션 배포가 가능한 완전한 API 레퍼런스 명세서로 문서화하십시오."

• Principal API Architect 페르소나: 멱등성(Idempotency), 보안 스코프(RBAC), 속도 제한(Rate Limiting) 등 프로덕션 아키텍처 요소를 강제함.
• RFC 7807 에러 스펙 준수: 표준 문제 세부정보(Problem Details) 구조를 강제하여 프론트엔드가 필드별 유효성 오류(invalid_params)를 즉시 UI 폼에 바인딩할 수 있도록 설계.
• Field-by-field Validation Rules: 최소/최대 길이, 정규식, 허용 열거형 값을 테이블로 박제.
• Zero-Fluff Negative Constraints: 얕은 {"data": "..."} 생략을 원천 봉쇄하고 실제 동작 가능한 curl 명령어 추출.

You are a Staff Full-Stack Systems Engineer and Frontend Architecture Specialist.
From the provided backend endpoint handler, extract the complete API Specification AND immediately generate the corresponding frontend client integration artifacts in TypeScript.

### Input Backend Code:
[PASTE_CONTROLLER_OR_ROUTE_CODE]

### Required Artifacts:
1. ENDPOINT CONTRACT SUMMARY:
   - HTTP Method, URI pattern, Auth scope, Request/Response payload contracts.

2. TYPESCRIPT DOMAIN DTOs & SCHEMAS:
   - Request interface and Response interface with strict typing (`readonly`, union literals for Enums, nullable types).
   - Corresponding Zod schema (`z.object({...})`) reflecting all backend validations (regex, min/max, email, uuid).

3. CLIENT INTEGRATION HOOK (TanStack Query / Axios):
   - Fully typed API caller function using `axios` or native `fetch`.
   - Custom React Hook using `@tanstack/react-query` (`useQuery` for GET, `useMutation` for POST/PUT/DELETE) with robust error typing based on RFC 7807.

4. EDGE-CASE ERROR MATRIX:
   - Explicit table mapping HTTP status codes -> Client-side UI error actions (e.g., 401 -> Redirect to `/login`, 422 -> Bind errors to React Hook Form fields).

활용 맥락: 백엔드 구현 완료 직후 프론트엔드 팀에게 넘겨줄 완벽한 TypeScript 계약(Contract)과 클라이언트 연동 훅이 필요한 풀스택 협업 상황에 최적화되어 있습니다.

{
  "id": "sub_1Q1h7b2eZvKYlo2CL8",
  "object": "subscription",
  "status": "active",
  "customerId": "cus_9f83a4c12",
  "planId": "PRO_MONTHLY",
  "currentPeriodStart": "2026-10-15T00:00:00Z",
  "currentPeriodEnd": "2026-11-15T00:00:00Z",
  "seatQuantity": 5,
  "unitPriceAmount": 2900,
  "currency": "USD"
}

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Request payload failed semantic validation rules.",
  "instance": "/v1/billing/subscriptions",
  "code": "PAYLOAD_VALIDATION_ERROR",
  "invalid_params": [
    { "name": "planId", "reason": "Value must be one of [STARTER_MONTHLY, PRO_MONTHLY, ENTERPRISE_ANNUAL]" }
  ]
}

curl -X POST "https://api.example.com/v1/billing/subscriptions" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{"customerId":"cus_9f83a4c12","planId":"PRO_MONTHLY","paymentMethodId":"pm_1Hh12X4K38xLpQ","quantity":5}'