muno-claude-plugin 1.7.0 → 1.9.0

package/templates/skills/swagger-docs-generator/reference/api-docs-template.md

@@ -0,0 +1,666 @@
+# [서비스 이름] API 문서
+
+> Generated from Swagger/OpenAPI
+> Version: [version]
+> Generated Date: [YYYY-MM-DD]
+
+---
+
+## 📋 목차
+
+- [개요](#개요)
+- [서버 정보](#서버-정보)
+- [인증](#인증)
+- [API 엔드포인트](#api-엔드포인트)
+- [데이터 모델](#데이터-모델)
+- [에러 코드](#에러-코드)
+
+---
+
+## 개요
+
+**서비스명**: [Service Title]
+**버전**: [version]
+**설명**: [description]
+
+### 주요 기능
+
+- 기능 1
+- 기능 2
+- 기능 3
+
+---
+
+## 서버 정보
+
+### Base URLs
+
+| 환경 | URL | 설명 |
+|------|-----|------|
+| Local | `http://localhost:8080` | 로컬 개발 서버 |
+| Development | `https://dev-api.example.com` | 개발 환경 |
+| Staging | `https://staging-api.example.com` | 스테이징 환경 |
+| Production | `https://api.example.com` | 프로덕션 환경 |
+
+### Contact
+
+- **Email**: [contact email]
+- **License**: [license name]
+
+---
+
+## 인증
+
+### Bearer Token
+
+이 API는 Bearer Token 인증을 사용합니다.
+
+**Header**:
+```
+Authorization: Bearer {token}
+```
+
+**토큰 획득 방법**:
+1. `/auth/login` 엔드포인트로 로그인
+2. 응답에서 `accessToken` 획득
+3. 모든 요청의 Authorization 헤더에 포함
+
+**Example**:
+```bash
+curl -X GET "https://api.example.com/api/users" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+---
+
+## API 엔드포인트
+
+### 👤 User
+
+사용자 관리 관련 API
+
+---
+
+#### `GET /api/users`
+
+사용자 목록을 조회합니다.
+
+**Parameters**:
+
+| Name | In | Type | Required | Description | Default |
+|------|-----|------|----------|-------------|---------|
+| page | query | integer | ❌ | Page number | 1 |
+| size | query | integer | ❌ | Page size | 20 |
+| sort | query | string | ❌ | Sort field | createdAt |
+| order | query | string | ❌ | Sort order (asc/desc) | desc |
+
+**Request Example**:
+
+```bash
+curl -X GET "http://localhost:8080/api/users?page=1&size=20" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Response**:
+
+- **200 OK**
+
+  ```json
+  {
+    "data": [
+      {
+        "id": 1,
+        "name": "John Doe",
+        "email": "john@example.com",
+        "role": "USER",
+        "createdAt": "2025-01-01T00:00:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "size": 20,
+      "totalElements": 100,
+      "totalPages": 5
+    }
+  }
+  ```
+
+- **401 Unauthorized**
+
+  ```json
+  {
+    "error": "UNAUTHORIZED",
+    "message": "Invalid or missing authentication token"
+  }
+  ```
+
+**Code Examples**:
+
+<details>
+<summary>JavaScript (fetch)</summary>
+
+```javascript
+const response = await fetch('http://localhost:8080/api/users?page=1&size=20', {
+  method: 'GET',
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  }
+});
+const data = await response.json();
+console.log(data);
+```
+</details>
+
+<details>
+<summary>Python (requests)</summary>
+
+```python
+import requests
+
+headers = {
+    'Authorization': f'Bearer {token}',
+    'Content-Type': 'application/json'
+}
+response = requests.get(
+    'http://localhost:8080/api/users',
+    headers=headers,
+    params={'page': 1, 'size': 20}
+)
+print(response.json())
+```
+</details>
+
+<details>
+<summary>Java (Spring WebClient)</summary>
+
+```java
+WebClient client = WebClient.create("http://localhost:8080");
+UserListResponse response = client.get()
+    .uri(uriBuilder -> uriBuilder
+        .path("/api/users")
+        .queryParam("page", 1)
+        .queryParam("size", 20)
+        .build())
+    .header("Authorization", "Bearer " + token)
+    .retrieve()
+    .bodyToMono(UserListResponse.class)
+    .block();
+```
+</details>
+
+<details>
+<summary>Kotlin (Spring WebClient)</summary>
+
+```kotlin
+val client = WebClient.create("http://localhost:8080")
+val response = client.get()
+    .uri { uriBuilder ->
+        uriBuilder
+            .path("/api/users")
+            .queryParam("page", 1)
+            .queryParam("size", 20)
+            .build()
+    }
+    .header("Authorization", "Bearer $token")
+    .retrieve()
+    .awaitBody<UserListResponse>()
+```
+</details>
+
+---
+
+#### `GET /api/users/{id}`
+
+특정 사용자의 상세 정보를 조회합니다.
+
+**Parameters**:
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| id | path | integer | ✅ | User ID |
+
+**Request Example**:
+
+```bash
+curl -X GET "http://localhost:8080/api/users/1" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Response**:
+
+- **200 OK**
+
+  ```json
+  {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+    "role": "USER",
+    "profile": {
+      "avatar": "https://example.com/avatar.jpg",
+      "bio": "Software Engineer"
+    },
+    "createdAt": "2025-01-01T00:00:00Z",
+    "updatedAt": "2025-01-01T00:00:00Z"
+  }
+  ```
+
+- **404 Not Found**
+
+  ```json
+  {
+    "error": "NOT_FOUND",
+    "message": "User not found with id: 1"
+  }
+  ```
+
+---
+
+#### `POST /api/users`
+
+새로운 사용자를 생성합니다.
+
+**Request Body**:
+
+```json
+{
+  "name": "string",
+  "email": "string",
+  "password": "string",
+  "role": "USER"
+}
+```
+
+**Request Example**:
+
+```bash
+curl -X POST "http://localhost:8080/api/users" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jane Doe",
+    "email": "jane@example.com",
+    "password": "securePassword123",
+    "role": "USER"
+  }'
+```
+
+**Response**:
+
+- **201 Created**
+
+  ```json
+  {
+    "id": 2,
+    "name": "Jane Doe",
+    "email": "jane@example.com",
+    "role": "USER",
+    "createdAt": "2025-01-01T00:00:00Z"
+  }
+  ```
+
+- **400 Bad Request**
+
+  ```json
+  {
+    "error": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email already exists"
+      }
+    ]
+  }
+  ```
+
+---
+
+#### `PUT /api/users/{id}`
+
+사용자 정보를 수정합니다.
+
+**Parameters**:
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| id | path | integer | ✅ | User ID |
+
+**Request Body**:
+
+```json
+{
+  "name": "string",
+  "email": "string",
+  "role": "USER"
+}
+```
+
+**Request Example**:
+
+```bash
+curl -X PUT "http://localhost:8080/api/users/1" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Updated",
+    "email": "john.updated@example.com"
+  }'
+```
+
+**Response**:
+
+- **200 OK**
+
+  ```json
+  {
+    "id": 1,
+    "name": "John Updated",
+    "email": "john.updated@example.com",
+    "role": "USER",
+    "updatedAt": "2025-01-01T12:00:00Z"
+  }
+  ```
+
+- **404 Not Found**
+
+  ```json
+  {
+    "error": "NOT_FOUND",
+    "message": "User not found with id: 1"
+  }
+  ```
+
+---
+
+#### `DELETE /api/users/{id}`
+
+사용자를 삭제합니다.
+
+**Parameters**:
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| id | path | integer | ✅ | User ID |
+
+**Request Example**:
+
+```bash
+curl -X DELETE "http://localhost:8080/api/users/1" \
+  -H "Authorization: Bearer {token}"
+```
+
+**Response**:
+
+- **204 No Content**
+
+  성공적으로 삭제됨 (본문 없음)
+
+- **404 Not Found**
+
+  ```json
+  {
+    "error": "NOT_FOUND",
+    "message": "User not found with id: 1"
+  }
+  ```
+
+---
+
+### 🔐 Authentication
+
+인증 관련 API
+
+---
+
+#### `POST /auth/login`
+
+사용자 로그인
+
+**Request Body**:
+
+```json
+{
+  "email": "string",
+  "password": "string"
+}
+```
+
+**Request Example**:
+
+```bash
+curl -X POST "http://localhost:8080/auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "john@example.com",
+    "password": "password123"
+  }'
+```
+
+**Response**:
+
+- **200 OK**
+
+  ```json
+  {
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "tokenType": "Bearer",
+    "expiresIn": 3600,
+    "user": {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john@example.com",
+      "role": "USER"
+    }
+  }
+  ```
+
+- **401 Unauthorized**
+
+  ```json
+  {
+    "error": "INVALID_CREDENTIALS",
+    "message": "Invalid email or password"
+  }
+  ```
+
+---
+
+#### `POST /auth/refresh`
+
+Access Token 갱신
+
+**Request Body**:
+
+```json
+{
+  "refreshToken": "string"
+}
+```
+
+**Response**:
+
+- **200 OK**
+
+  ```json
+  {
+    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "tokenType": "Bearer",
+    "expiresIn": 3600
+  }
+  ```
+
+- **401 Unauthorized**
+
+  ```json
+  {
+    "error": "INVALID_TOKEN",
+    "message": "Refresh token is invalid or expired"
+  }
+  ```
+
+---
+
+## 데이터 모델
+
+### User
+
+사용자 정보
+
+```json
+{
+  "id": "integer",
+  "name": "string",
+  "email": "string",
+  "role": "string",
+  "profile": "UserProfile",
+  "createdAt": "string (date-time)",
+  "updatedAt": "string (date-time)"
+}
+```
+
+**Properties**:
+
+| Field | Type | Required | Description | Constraints |
+|-------|------|----------|-------------|-------------|
+| id | integer | ✅ | User ID | Auto-generated |
+| name | string | ✅ | User name | 2-50 characters |
+| email | string | ✅ | User email | Valid email format |
+| role | string | ✅ | User role | Enum: USER, ADMIN |
+| profile | UserProfile | ❌ | User profile | - |
+| createdAt | string | ✅ | Created timestamp | ISO 8601 format |
+| updatedAt | string | ✅ | Updated timestamp | ISO 8601 format |
+
+---
+
+### UserProfile
+
+사용자 프로필 정보
+
+```json
+{
+  "avatar": "string",
+  "bio": "string",
+  "phone": "string"
+}
+```
+
+**Properties**:
+
+| Field | Type | Required | Description | Constraints |
+|-------|------|----------|-------------|-------------|
+| avatar | string | ❌ | Avatar URL | Valid URL |
+| bio | string | ❌ | User bio | Max 200 characters |
+| phone | string | ❌ | Phone number | E.164 format |
+
+---
+
+### PaginationResponse
+
+페이지네이션 정보
+
+```json
+{
+  "page": "integer",
+  "size": "integer",
+  "totalElements": "integer",
+  "totalPages": "integer"
+}
+```
+
+**Properties**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| page | integer | Current page number (1-indexed) |
+| size | integer | Page size |
+| totalElements | integer | Total number of elements |
+| totalPages | integer | Total number of pages |
+
+---
+
+### ErrorResponse
+
+에러 응답 형식
+
+```json
+{
+  "error": "string",
+  "message": "string",
+  "details": "array"
+}
+```
+
+**Properties**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| error | string | Error code |
+| message | string | Human-readable error message |
+| details | array | Additional error details (optional) |
+
+---
+
+## 에러 코드
+
+### HTTP Status Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 200 | OK | Request succeeded |
+| 201 | Created | Resource created successfully |
+| 204 | No Content | Request succeeded with no response body |
+| 400 | Bad Request | Invalid request parameters |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 409 | Conflict | Resource conflict (e.g., duplicate email) |
+| 422 | Unprocessable Entity | Validation error |
+| 500 | Internal Server Error | Server error |
+| 503 | Service Unavailable | Service temporarily unavailable |
+
+### Application Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| VALIDATION_ERROR | 400 | Input validation failed |
+| INVALID_CREDENTIALS | 401 | Invalid email or password |
+| UNAUTHORIZED | 401 | Missing or invalid token |
+| FORBIDDEN | 403 | Insufficient permissions |
+| NOT_FOUND | 404 | Resource not found |
+| DUPLICATE_EMAIL | 409 | Email already exists |
+| INTERNAL_ERROR | 500 | Internal server error |
+
+---
+
+## 부록
+
+### Rate Limiting
+
+- **제한**: 100 requests per minute per user
+- **Header**:
+  - `X-RateLimit-Limit`: 최대 요청 수
+  - `X-RateLimit-Remaining`: 남은 요청 수
+  - `X-RateLimit-Reset`: 제한 초기화 시각 (Unix timestamp)
+
+### Changelog
+
+#### Version 1.0.0 (2025-01-01)
+- Initial release
+- User CRUD operations
+- Authentication (JWT)
+
+---
+
+## 링크
+
+- **Swagger UI**: http://localhost:8080/swagger-ui.html
+- **API Docs JSON**: http://localhost:8080/v3/api-docs
+- **Postman Collection**: [Download](./postman-collection.json)
+
+---
+
+> 📝 이 문서는 Swagger/OpenAPI 명세로부터 자동 생성되었습니다.
+> 마지막 업데이트: [YYYY-MM-DD HH:mm:ss]