muno-claude-plugin 1.7.0 → 1.9.0

package/templates/skills/swagger-docs-generator/SKILL.md

@@ -0,0 +1,699 @@
+---
+name: swagger-docs-generator
+description: |
+  Swagger/OpenAPI 문서를 읽어서 개발자가 읽기 쉬운 Markdown API 명세로 변환합니다.
+  "API 문서 만들어줘", "Swagger 문서 변환", "API 명세 생성", "OpenAPI 문서" 등의 요청에 사용합니다.
+  서버가 제공하는 Swagger JSON을 자동으로 파싱하여 체계적인 문서를 생성합니다.
+allowed-tools: Read, Write, WebFetch, Grep, Glob
+---
+
+# Swagger Docs Generator
+
+## 페르소나
+
+@.claude/personas/dev.md
+
+> **Swagger Docs Generator의 역할**: 서버의 Swagger/OpenAPI 문서를 읽어서 개발자 친화적인 Markdown 문서로 변환합니다.
+> API 엔드포인트, 요청/응답 스키마, 에러 코드 등을 명확하게 정리합니다.
+
+---
+
+## 기본 설정
+
+### 기본 주소
+
+```
+Host: localhost (또는 자동 감지된 로컬 IP)
+Port: 8080
+Swagger Docs Path: /v3/api-docs
+
+Full URL: http://localhost:8080/v3/api-docs
+또는: http://192.168.x.x:8080/v3/api-docs (로컬 IP 자동 감지)
+```
+
+### 로컬 IP 자동 감지
+
+사용자가 주소를 제공하지 않으면 자동으로 로컬 IP를 감지합니다:
+
+**Bash 스크립트**:
+```bash
+# macOS/Linux
+LOCAL_IP=$(ifconfig | grep "inet " | grep -v 127.0.0.1 | awk '{print $2}' | head -n 1)
+
+# 또는 더 정확하게
+LOCAL_IP=$(ipconfig getifaddr en0)  # macOS WiFi
+LOCAL_IP=$(ipconfig getifaddr en1)  # macOS Ethernet
+
+# Linux
+LOCAL_IP=$(hostname -I | awk '{print $1}')
+```
+
+**감지 우선순위**:
+1. WiFi 인터페이스 (en0, wlan0)
+2. Ethernet 인터페이스 (en1, eth0)
+3. localhost (127.0.0.1)
+
+**예시 출력**:
+```
+🔍 로컬 IP 자동 감지 중...
+
+감지된 IP 주소:
+1. 192.168.0.100 (WiFi - en0)
+2. 172.16.0.50 (Ethernet - en1)
+3. 127.0.0.1 (localhost)
+
+어떤 주소를 사용하시겠습니까? (기본: 1)
+```
+
+### 지원 형식
+
+- OpenAPI 3.0.x
+- Swagger 2.0
+- JSON 형식
+
+---
+
+## 워크플로우
+
+```mermaid
+flowchart TD
+    A[사용자 요청] --> B{호스트 정보 제공?}
+    B -->|Yes| C[제공된 주소 사용]
+    B -->|No| D[기본 주소 사용<br/>localhost:8080/v3/api-docs]
+    C --> E[Swagger JSON 가져오기]
+    D --> E
+    E --> F{JSON 로드 성공?}
+    F -->|No| G[에러: 연결 실패<br/>주소 확인 요청]
+    F -->|Yes| H[OpenAPI 버전 확인]
+    H --> I[API 정보 파싱]
+    I --> J[엔드포인트별 정리]
+    J --> K[스키마 정의 추출]
+    K --> L[Markdown 문서 생성]
+    L --> M[파일 저장<br/>documents/api/]
+    M --> N[사용자에게 결과 전달]
+```
+
+---
+
+## 사용 방법
+
+### 1. 기본 사용 (로컬 서버)
+
+```
+/swagger-docs-generator
+
+로컬 서버의 API 문서를 생성해주세요.
+```
+
+자동 감지 프로세스:
+1. 로컬 IP 감지 (192.168.x.x)
+2. 감지된 IP가 여러 개면 선택 요청
+3. 선택된 IP + 기본 포트(8080) + 기본 경로(/v3/api-docs) 조합
+4. `http://192.168.0.100:8080/v3/api-docs` 접근
+
+로컬 IP 감지 실패 시 `http://localhost:8080/v3/api-docs` 사용
+
+### 2. 커스텀 호스트/포트
+
+```
+/swagger-docs-generator
+
+http://localhost:3000/v3/api-docs 의 API 문서를 생성해주세요.
+```
+
+### 3. 원격 서버
+
+```
+/swagger-docs-generator
+
+https://api.example.com/v3/api-docs 의 API 문서를 생성해주세요.
+```
+
+### 4. 다른 Swagger 경로
+
+```
+/swagger-docs-generator
+
+http://localhost:8080/api-docs 의 API 문서를 생성해주세요.
+```
+
+---
+
+## 정보 수집
+
+### 필수 정보
+
+1. **Swagger 문서 URL**
+   - 제공되지 않으면 기본값 사용
+   - 형식: `http(s)://host:port/path`
+
+2. **서비스 이름** (선택)
+   - 파일명에 사용
+   - 제공되지 않으면 swagger JSON의 `info.title` 사용
+
+### 질문 예시
+
+```
+사용자가 주소를 제공하지 않은 경우:
+
+"Swagger 문서 주소를 알려주세요.
+기본값은 http://localhost:8080/v3/api-docs 입니다.
+그대로 사용하시겠습니까?"
+```
+
+---
+
+## Swagger JSON 파싱
+
+### OpenAPI 3.0 구조
+
+```json
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "서비스 이름",
+    "description": "서비스 설명",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:8080",
+      "description": "Local server"
+    }
+  ],
+  "paths": {
+    "/api/users": {
+      "get": {
+        "summary": "사용자 목록 조회",
+        "tags": ["User"],
+        "parameters": [...],
+        "responses": {...}
+      },
+      "post": {...}
+    }
+  },
+  "components": {
+    "schemas": {...}
+  }
+}
+```
+
+### Swagger 2.0 구조
+
+```json
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "서비스 이름",
+    "version": "1.0.0"
+  },
+  "host": "localhost:8080",
+  "basePath": "/api",
+  "paths": {...},
+  "definitions": {...}
+}
+```
+
+---
+
+## Markdown 문서 구조
+
+### 템플릿
+
+```markdown
+# [서비스 이름] API 문서
+
+> Generated from Swagger/OpenAPI
+> Version: [version]
+> Base URL: [baseUrl]
+
+## 개요
+
+[description]
+
+---
+
+## 서버 정보
+
+- **Base URL**: `[baseUrl]`
+- **환경**: [environment]
+
+---
+
+## 인증
+
+[인증 방식 설명]
+
+---
+
+## API 엔드포인트
+
+### [Tag Name]
+
+#### `[METHOD] [PATH]`
+
+**Summary**: [summary]
+
+**Description**: [description]
+
+**Parameters**:
+
+| Name | In | Type | Required | Description |
+|------|-----|------|----------|-------------|
+| id | path | integer | ✅ | User ID |
+| page | query | integer | ❌ | Page number (default: 1) |
+
+**Request Body**:
+
+```json
+{
+  "name": "string",
+  "email": "string"
+}
+```
+
+**Responses**:
+
+- **200 OK**
+  ```json
+  {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+  ```
+
+- **400 Bad Request**
+  ```json
+  {
+    "error": "Invalid input"
+  }
+  ```
+
+- **404 Not Found**
+  ```json
+  {
+    "error": "User not found"
+  }
+  ```
+
+---
+
+## 데이터 모델
+
+### User
+
+```json
+{
+  "id": "integer",
+  "name": "string",
+  "email": "string",
+  "createdAt": "string (date-time)"
+}
+```
+
+**Properties**:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | integer | ✅ | User ID |
+| name | string | ✅ | User name |
+| email | string | ✅ | User email |
+| createdAt | string | ✅ | ISO 8601 date-time |
+
+---
+
+## 에러 코드
+
+| Code | Message | Description |
+|------|---------|-------------|
+| 400 | Bad Request | Invalid input parameters |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 500 | Internal Server Error | Server error |
+```
+
+---
+
+## 파싱 로직
+
+### 1. 기본 정보 추출
+
+```javascript
+{
+  title: swagger.info.title,
+  version: swagger.info.version,
+  description: swagger.info.description,
+  baseUrl: swagger.servers?.[0]?.url || swagger.host + swagger.basePath
+}
+```
+
+### 2. 엔드포인트 파싱
+
+각 `paths` 객체를 순회하며:
+
+```javascript
+for (path in swagger.paths) {
+  for (method in swagger.paths[path]) {
+    endpoint = {
+      method: method.toUpperCase(),
+      path: path,
+      summary: operation.summary,
+      description: operation.description,
+      tags: operation.tags,
+      parameters: operation.parameters,
+      requestBody: operation.requestBody,
+      responses: operation.responses
+    }
+  }
+}
+```
+
+### 3. 태그별 그룹핑
+
+```javascript
+const groupedByTag = endpoints.reduce((acc, endpoint) => {
+  const tag = endpoint.tags?.[0] || 'Default';
+  if (!acc[tag]) acc[tag] = [];
+  acc[tag].push(endpoint);
+  return acc;
+}, {});
+```
+
+### 4. 스키마 참조 해석
+
+```javascript
+// $ref: "#/components/schemas/User"
+// 또는 $ref: "#/definitions/User"
+
+function resolveRef(ref, swagger) {
+  const path = ref.replace('#/', '').split('/');
+  let schema = swagger;
+  for (const key of path) {
+    schema = schema[key];
+  }
+  return schema;
+}
+```
+
+---
+
+## 특별 처리
+
+### 1. 인증 정보
+
+```javascript
+// OpenAPI 3.0
+if (swagger.components?.securitySchemes) {
+  // Bearer, OAuth2, API Key 등 파싱
+}
+
+// Swagger 2.0
+if (swagger.securityDefinitions) {
+  // 인증 방식 파싱
+}
+```
+
+### 2. 예제 데이터
+
+```javascript
+// 우선순위:
+// 1. example (단일 예제)
+// 2. examples (여러 예제)
+// 3. 스키마로부터 자동 생성
+
+if (schema.example) {
+  return schema.example;
+} else if (schema.examples) {
+  return Object.values(schema.examples)[0];
+} else {
+  return generateExampleFromSchema(schema);
+}
+```
+
+### 3. Enum 값
+
+```javascript
+if (schema.enum) {
+  // Enum 값 표시
+  return `enum: [${schema.enum.join(', ')}]`;
+}
+```
+
+### 4. Array 타입
+
+```javascript
+if (schema.type === 'array') {
+  const itemType = schema.items.type || schema.items.$ref;
+  return `array<${itemType}>`;
+}
+```
+
+---
+
+## 저장 위치
+
+```
+documents/api/
+├── [service-name]-api-docs.md     # 전체 API 문서
+└── [service-name]-postman.json    # Postman Collection (선택)
+```
+
+### 파일명 규칙
+
+1. Swagger의 `info.title`을 kebab-case로 변환
+   - "User Service" → `user-service-api-docs.md`
+2. 사용자가 서비스 이름 제공 시 사용
+3. 기본값: `api-docs.md`
+
+---
+
+## 에러 처리
+
+### 1. 연결 실패
+
+```markdown
+❌ Swagger 문서를 가져올 수 없습니다.
+
+**주소**: http://localhost:8080/v3/api-docs
+
+**가능한 원인**:
+- 서버가 실행되지 않음
+- 포트가 다름
+- Swagger 경로가 다름
+
+**해결 방법**:
+1. 서버가 실행 중인지 확인
+2. 올바른 포트 확인 (기본: 8080)
+3. Swagger 문서 경로 확인 (/v3/api-docs, /swagger-ui/api-docs 등)
+```
+
+### 2. JSON 파싱 실패
+
+```markdown
+❌ Swagger 문서 형식이 올바르지 않습니다.
+
+반환된 데이터가 JSON이 아니거나 Swagger/OpenAPI 형식이 아닙니다.
+```
+
+### 3. 빈 문서
+
+```markdown
+⚠️ API 엔드포인트가 없습니다.
+
+Swagger 문서에 정의된 경로(paths)가 없습니다.
+서버 설정을 확인해주세요.
+```
+
+---
+
+## 고급 기능
+
+### 1. 여러 서버의 문서 통합
+
+```
+/swagger-docs-generator
+
+다음 서버들의 API 문서를 통합해주세요:
+- Auth Service: http://localhost:8080/v3/api-docs
+- User Service: http://localhost:8081/v3/api-docs
+- Order Service: http://localhost:8082/v3/api-docs
+```
+
+각 서비스별로 섹션 분리하여 하나의 문서 생성
+
+### 2. Postman Collection 생성 (선택)
+
+Swagger JSON을 Postman Collection v2.1 형식으로 변환:
+
+```json
+{
+  "info": {
+    "name": "User Service API",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Users",
+      "item": [
+        {
+          "name": "Get Users",
+          "request": {
+            "method": "GET",
+            "url": "{{baseUrl}}/api/users"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 3. cURL 예제 생성
+
+각 엔드포인트에 cURL 예제 추가:
+
+```bash
+# Get user by ID
+curl -X GET "http://localhost:8080/api/users/1" \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/json"
+
+# Create user
+curl -X POST "http://localhost:8080/api/users" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "John Doe",
+    "email": "john@example.com"
+  }'
+```
+
+---
+
+## 실행 예시
+
+### Input
+
+```
+/swagger-docs-generator
+
+http://localhost:8080/v3/api-docs 의 API 문서를 생성해주세요.
+서비스 이름은 "User Service" 입니다.
+```
+
+### Process
+
+1. WebFetch로 `http://localhost:8080/v3/api-docs` 요청
+2. JSON 파싱
+3. 엔드포인트 추출 및 태그별 그룹핑
+4. 스키마 정의 추출
+5. Markdown 문서 생성
+6. `documents/api/user-service-api-docs.md` 저장
+
+### Output
+
+```markdown
+✅ API 문서가 생성되었습니다.
+
+**파일**: documents/api/user-service-api-docs.md
+
+**내용**:
+- 서비스 정보
+- 12개 API 엔드포인트
+- 5개 데이터 모델
+- 인증 방식: Bearer Token
+
+**엔드포인트 요약**:
+- GET /api/users - 사용자 목록 조회
+- GET /api/users/{id} - 사용자 조회
+- POST /api/users - 사용자 생성
+- PUT /api/users/{id} - 사용자 수정
+- DELETE /api/users/{id} - 사용자 삭제
+...
+```
+
+---
+
+## 추측 금지 원칙
+
+```
+정보가 충분하면 → 바로 생성
+정보가 부족하면 → 추측하지 말고 질문
+
+✅ 질문해야 할 때:
+   • Swagger 문서 주소를 모를 때
+   • 서버에 접근할 수 없을 때
+   • 여러 서버 중 어떤 것인지 불명확할 때
+
+❌ 질문하지 말아야 할 때:
+   • 기본 포트(8080) 사용 시
+   • 표준 Swagger 경로(/v3/api-docs) 사용 시
+   • Swagger JSON 형식이 표준일 때
+```
+
+---
+
+## 참고 템플릿
+
+상세한 Markdown 템플릿은 다음 파일 참고:
+- `reference/api-docs-template.md`
+
+---
+
+## 개발자를 위한 팁
+
+### Swagger UI 확인
+
+생성된 문서와 함께 Swagger UI 링크 제공:
+
+```markdown
+🔗 **Swagger UI**: http://localhost:8080/swagger-ui.html
+```
+
+### API 테스트
+
+각 엔드포인트에 "Try it out" 섹션 추가:
+
+```markdown
+#### 테스트
+
+**cURL**:
+```bash
+curl -X GET "http://localhost:8080/api/users/1"
+```
+
+**JavaScript (fetch)**:
+```javascript
+fetch('http://localhost:8080/api/users/1')
+  .then(res => res.json())
+  .then(data => console.log(data));
+```
+
+**Python (requests)**:
+```python
+import requests
+response = requests.get('http://localhost:8080/api/users/1')
+print(response.json())
+```
+```
+
+---
+
+## 버전 관리
+
+API 문서를 버전별로 관리:
+
+```
+documents/api/
+├── user-service-api-docs.md        # Latest
+├── v1/
+│   └── user-service-api-docs.md
+└── v2/
+    └── user-service-api-docs.md
+```
+
+버전 정보를 파일명에 포함:
+```
+documents/api/user-service-v2-api-docs.md
+```