muno-claude-plugin 1.9.0 → 1.10.0

package/bin/cli.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const VERSION = '1.9.0';
+const VERSION = '1.10.0';
 const PACKAGE_NAME = 'muno-claude-plugin';
 
 // ANSI colors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muno-claude-plugin",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Unleash Claude Code's full power - Complete development workflow with expert personas, TDD-based agents, and automated documentation",
   "main": "bin/cli.js",
   "bin": {

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

@@ -4,7 +4,7 @@ description: |
   Swagger/OpenAPI 문서를 읽어서 개발자가 읽기 쉬운 Markdown API 명세로 변환합니다.
   "API 문서 만들어줘", "Swagger 문서 변환", "API 명세 생성", "OpenAPI 문서" 등의 요청에 사용합니다.
   서버가 제공하는 Swagger JSON을 자동으로 파싱하여 체계적인 문서를 생성합니다.
-allowed-tools: Read, Write, WebFetch, Grep, Glob
+allowed-tools: Read, Write, WebFetch, Grep, Glob, Bash
 ---
 
 # Swagger Docs Generator
@@ -571,6 +571,76 @@ curl -X POST "http://localhost:8080/api/users" \
 
 ---
 
+## 실행 방법
+
+### 스크립트 활용
+
+이 스킬은 파이썬 스크립트를 사용하여 Swagger 문서를 변환합니다.
+
+#### 1. 로컬 IP 감지
+
+```bash
+# 스크립트 위치: scripts/get-local-ip.py
+SKILL_DIR=$(pwd)/.claude/skills/swagger-docs-generator
+
+# 로컬 IP 감지
+python3 $SKILL_DIR/scripts/get-local-ip.py
+
+# 출력 예시:
+# [
+#   {"ip": "192.168.0.100", "interface": "en0", "type": "WiFi"},
+#   {"ip": "127.0.0.1", "interface": "lo0", "type": "Loopback"}
+# ]
+```
+
+#### 2. Swagger → Markdown 변환
+
+```bash
+# 스크립트 위치: scripts/swagger-to-markdown.py
+SKILL_DIR=$(pwd)/.claude/skills/swagger-docs-generator
+
+# 기본 사용
+python3 $SKILL_DIR/scripts/swagger-to-markdown.py http://localhost:8080/v3/api-docs
+
+# 파일로 저장
+python3 $SKILL_DIR/scripts/swagger-to-markdown.py \
+  http://localhost:8080/v3/api-docs \
+  documents/api/user-service-api-docs.md
+
+# 로컬 IP 자동 감지 + 변환 (통합 실행)
+LOCAL_IP=$(python3 $SKILL_DIR/scripts/get-local-ip.py | jq -r '.[0].ip')
+python3 $SKILL_DIR/scripts/swagger-to-markdown.py \
+  http://$LOCAL_IP:8080/v3/api-docs \
+  documents/api/api-docs.md
+```
+
+#### 3. 스킬 워크플로우
+
+사용자가 `/swagger-docs-generator`를 호출하면:
+
+1. **로컬 IP 감지**
+   ```bash
+   python3 scripts/get-local-ip.py
+   ```
+
+2. **사용자 확인** (여러 IP가 감지되면)
+   - 감지된 IP 목록 표시
+   - 사용자 선택 받기
+
+3. **Swagger 문서 변환**
+   ```bash
+   python3 scripts/swagger-to-markdown.py \
+     http://{selected_ip}:{port}/v3/api-docs \
+     documents/api/{service-name}-api-docs.md
+   ```
+
+4. **결과 전달**
+   - 생성된 파일 경로
+   - API 엔드포인트 요약
+   - Swagger UI 링크
+
+---
+
 ## 실행 예시
 
 ### Input
@@ -584,12 +654,10 @@ http://localhost:8080/v3/api-docs 의 API 문서를 생성해주세요.
 
 ### Process
 
-1. WebFetch로 `http://localhost:8080/v3/api-docs` 요청
-2. JSON 파싱
-3. 엔드포인트 추출 및 태그별 그룹핑
-4. 스키마 정의 추출
-5. Markdown 문서 생성
-6. `documents/api/user-service-api-docs.md` 저장
+1. `python3 scripts/swagger-to-markdown.py` 실행
+2. Swagger JSON 가져오기
+3. JSON 파싱 및 Markdown 생성
+4. `documents/api/user-service-api-docs.md` 저장
 
 ### Output
 
@@ -634,10 +702,10 @@ http://localhost:8080/v3/api-docs 의 API 문서를 생성해주세요.
 
 ---
 
-## 참고 템플릿
+## 참고 문서
 
-상세한 Markdown 템플릿은 다음 파일 참고:
-- `reference/api-docs-template.md`
+상세한 Markdown 템플릿 예시:
+- [reference/api-docs-template.md](reference/api-docs-template.md) - API 문서 템플릿 및 예시
 
 ---
 

package/templates/skills/swagger-docs-generator/scripts/get-local-ip.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+로컬 IP 주소를 자동으로 감지하는 스크립트
+
+Usage:
+    python get-local-ip.py
+
+Output:
+    JSON 형식으로 감지된 IP 주소 목록 출력
+    [
+        {"ip": "192.168.0.100", "interface": "en0", "type": "WiFi"},
+        {"ip": "172.16.0.50", "interface": "en1", "type": "Ethernet"},
+        {"ip": "127.0.0.1", "interface": "lo0", "type": "Loopback"}
+    ]
+"""
+
+import socket
+import json
+import platform
+import subprocess
+from typing import List, Dict
+
+def get_local_ips() -> List[Dict[str, str]]:
+    """모든 네트워크 인터페이스의 IP 주소를 감지"""
+    ips = []
+
+    # Method 1: socket을 이용한 기본 IP 감지 (가장 신뢰할 수 있는 방법)
+    try:
+        # 외부 연결을 시뮬레이션하여 실제 사용되는 IP 얻기
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.settimeout(0.1)
+        try:
+            # Google DNS에 연결 (실제로 패킷을 보내지 않음)
+            s.connect(('8.8.8.8', 80))
+            primary_ip = s.getsockname()[0]
+            ips.append({
+                'ip': primary_ip,
+                'interface': 'primary',
+                'type': 'Primary',
+                'priority': 1
+            })
+        except Exception:
+            pass
+        finally:
+            s.close()
+    except Exception:
+        pass
+
+    # Method 2: 플랫폼별 네트워크 인터페이스 조회
+    system = platform.system()
+
+    if system == 'Darwin':  # macOS
+        ips.extend(get_macos_ips())
+    elif system == 'Linux':
+        ips.extend(get_linux_ips())
+    elif system == 'Windows':
+        ips.extend(get_windows_ips())
+
+    # 중복 제거 (IP 기준)
+    seen_ips = set()
+    unique_ips = []
+    for ip_info in ips:
+        if ip_info['ip'] not in seen_ips:
+            seen_ips.add(ip_info['ip'])
+            unique_ips.append(ip_info)
+
+    # 우선순위 정렬
+    unique_ips.sort(key=lambda x: (
+        x.get('priority', 99),  # 우선순위
+        0 if x['ip'].startswith('192.168.') else 1,  # 사설 IP 우선
+        x['ip']  # IP 주소
+    ))
+
+    return unique_ips
+
+def get_macos_ips() -> List[Dict[str, str]]:
+    """macOS에서 IP 주소 감지"""
+    ips = []
+
+    try:
+        # ifconfig 명령어 실행
+        result = subprocess.run(
+            ['ifconfig'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+
+        if result.returncode == 0:
+            current_interface = None
+            interface_type = 'Unknown'
+
+            for line in result.stdout.split('\n'):
+                line = line.strip()
+
+                # 인터페이스 이름 감지
+                if line and not line.startswith(' ') and ':' in line:
+                    current_interface = line.split(':')[0]
+
+                    # 인터페이스 타입 판단
+                    if current_interface.startswith('en0'):
+                        interface_type = 'WiFi'
+                    elif current_interface.startswith('en1'):
+                        interface_type = 'Ethernet'
+                    elif current_interface.startswith('lo'):
+                        interface_type = 'Loopback'
+                    else:
+                        interface_type = 'Other'
+
+                # inet 주소 추출
+                if 'inet ' in line and current_interface:
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        ip = parts[1]
+
+                        # 우선순위 결정
+                        priority = 10
+                        if interface_type == 'WiFi':
+                            priority = 2
+                        elif interface_type == 'Ethernet':
+                            priority = 3
+                        elif interface_type == 'Loopback':
+                            priority = 99
+
+                        ips.append({
+                            'ip': ip,
+                            'interface': current_interface,
+                            'type': interface_type,
+                            'priority': priority
+                        })
+
+        # ipconfig 명령어로 추가 시도
+        for interface in ['en0', 'en1', 'en2']:
+            try:
+                result = subprocess.run(
+                    ['ipconfig', 'getifaddr', interface],
+                    capture_output=True,
+                    text=True,
+                    timeout=2
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    ip = result.stdout.strip()
+                    interface_type = 'WiFi' if interface == 'en0' else 'Ethernet'
+                    priority = 2 if interface == 'en0' else 3
+
+                    ips.append({
+                        'ip': ip,
+                        'interface': interface,
+                        'type': interface_type,
+                        'priority': priority
+                    })
+            except Exception:
+                continue
+
+    except Exception as e:
+        print(f"macOS IP detection error: {e}", file=sys.stderr)
+
+    return ips
+
+def get_linux_ips() -> List[Dict[str, str]]:
+    """Linux에서 IP 주소 감지"""
+    ips = []
+
+    try:
+        # hostname -I 명령어
+        result = subprocess.run(
+            ['hostname', '-I'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+
+        if result.returncode == 0:
+            for idx, ip in enumerate(result.stdout.strip().split()):
+                ips.append({
+                    'ip': ip,
+                    'interface': f'auto-{idx}',
+                    'type': 'Auto-detected',
+                    'priority': 5 + idx
+                })
+
+        # ip addr 명령어
+        result = subprocess.run(
+            ['ip', 'addr'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+
+        if result.returncode == 0:
+            current_interface = None
+            interface_type = 'Unknown'
+
+            for line in result.stdout.split('\n'):
+                line = line.strip()
+
+                # 인터페이스 감지
+                if line and line[0].isdigit() and ':' in line:
+                    parts = line.split(':')
+                    if len(parts) >= 2:
+                        current_interface = parts[1].strip()
+
+                        if 'wlan' in current_interface or 'wlp' in current_interface:
+                            interface_type = 'WiFi'
+                        elif 'eth' in current_interface or 'enp' in current_interface:
+                            interface_type = 'Ethernet'
+                        elif 'lo' in current_interface:
+                            interface_type = 'Loopback'
+                        else:
+                            interface_type = 'Other'
+
+                # IP 주소 추출
+                if 'inet ' in line and current_interface:
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        ip_with_mask = parts[1]
+                        ip = ip_with_mask.split('/')[0]
+
+                        priority = 10
+                        if interface_type == 'WiFi':
+                            priority = 2
+                        elif interface_type == 'Ethernet':
+                            priority = 3
+                        elif interface_type == 'Loopback':
+                            priority = 99
+
+                        ips.append({
+                            'ip': ip,
+                            'interface': current_interface,
+                            'type': interface_type,
+                            'priority': priority
+                        })
+
+    except Exception as e:
+        print(f"Linux IP detection error: {e}", file=sys.stderr)
+
+    return ips
+
+def get_windows_ips() -> List[Dict[str, str]]:
+    """Windows에서 IP 주소 감지"""
+    ips = []
+
+    try:
+        # ipconfig 명령어
+        result = subprocess.run(
+            ['ipconfig'],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            encoding='cp949'  # Windows 인코딩
+        )
+
+        if result.returncode == 0:
+            current_adapter = None
+            adapter_type = 'Unknown'
+
+            for line in result.stdout.split('\n'):
+                line = line.strip()
+
+                # 어댑터 이름 감지
+                if 'adapter' in line.lower() or '어댑터' in line:
+                    current_adapter = line.split(':')[0].strip()
+
+                    if 'wireless' in line.lower() or '무선' in line:
+                        adapter_type = 'WiFi'
+                    elif 'ethernet' in line.lower() or '이더넷' in line:
+                        adapter_type = 'Ethernet'
+                    else:
+                        adapter_type = 'Other'
+
+                # IPv4 주소 추출
+                if ('IPv4' in line or 'IPv4 주소' in line) and ':' in line:
+                    ip = line.split(':')[-1].strip()
+                    # (기본 설정) 같은 문구 제거
+                    ip = ip.replace('(기본 설정)', '').strip()
+
+                    priority = 10
+                    if adapter_type == 'WiFi':
+                        priority = 2
+                    elif adapter_type == 'Ethernet':
+                        priority = 3
+
+                    ips.append({
+                        'ip': ip,
+                        'interface': current_adapter or 'unknown',
+                        'type': adapter_type,
+                        'priority': priority
+                    })
+
+    except Exception as e:
+        print(f"Windows IP detection error: {e}", file=sys.stderr)
+
+    return ips
+
+def main():
+    """메인 함수"""
+    try:
+        ips = get_local_ips()
+
+        if not ips:
+            # 기본값으로 localhost 추가
+            ips.append({
+                'ip': '127.0.0.1',
+                'interface': 'lo0',
+                'type': 'Loopback',
+                'priority': 99
+            })
+
+        # JSON 출력 (priority 제외)
+        output = []
+        for ip_info in ips:
+            output.append({
+                'ip': ip_info['ip'],
+                'interface': ip_info['interface'],
+                'type': ip_info['type']
+            })
+
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+
+    except Exception as e:
+        import sys
+        print(json.dumps({
+            'error': str(e),
+            'ips': [{'ip': '127.0.0.1', 'interface': 'lo0', 'type': 'Loopback'}]
+        }, indent=2), file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

package/templates/skills/swagger-docs-generator/scripts/swagger-to-markdown.py

@@ -0,0 +1,416 @@
+#!/usr/bin/env python3
+"""
+Swagger/OpenAPI JSON을 Markdown 문서로 변환하는 스크립트
+
+Usage:
+    python swagger-to-markdown.py <swagger_url> [output_file]
+    python swagger-to-markdown.py http://localhost:8080/v3/api-docs
+    python swagger-to-markdown.py http://localhost:8080/v3/api-docs api-docs.md
+
+Requirements:
+    pip install requests
+"""
+
+import sys
+import json
+import requests
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+from urllib.parse import urlparse
+
+def fetch_swagger(url: str) -> Dict[str, Any]:
+    """Swagger JSON 가져오기"""
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Failed to fetch Swagger docs from {url}")
+        print(f"Error: {e}")
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"❌ Invalid JSON response from {url}")
+        print(f"Error: {e}")
+        sys.exit(1)
+
+def get_base_url(swagger: Dict[str, Any]) -> str:
+    """Base URL 추출"""
+    # OpenAPI 3.0
+    if 'servers' in swagger and swagger['servers']:
+        return swagger['servers'][0].get('url', '')
+
+    # Swagger 2.0
+    if 'host' in swagger:
+        scheme = swagger.get('schemes', ['http'])[0]
+        host = swagger['host']
+        base_path = swagger.get('basePath', '')
+        return f"{scheme}://{host}{base_path}"
+
+    return ''
+
+def resolve_ref(ref: str, swagger: Dict[str, Any]) -> Dict[str, Any]:
+    """$ref 참조 해석"""
+    if not ref.startswith('#/'):
+        return {}
+
+    parts = ref.replace('#/', '').split('/')
+    result = swagger
+
+    for part in parts:
+        if part in result:
+            result = result[part]
+        else:
+            return {}
+
+    return result
+
+def get_schema_type(schema: Dict[str, Any], swagger: Dict[str, Any]) -> str:
+    """스키마 타입 문자열 생성"""
+    if '$ref' in schema:
+        ref_name = schema['$ref'].split('/')[-1]
+        return ref_name
+
+    schema_type = schema.get('type', 'object')
+
+    if schema_type == 'array':
+        items = schema.get('items', {})
+        item_type = get_schema_type(items, swagger)
+        return f"array<{item_type}>"
+
+    if 'enum' in schema:
+        return f"enum: [{', '.join(map(str, schema['enum']))}]"
+
+    format_type = schema.get('format')
+    if format_type:
+        return f"{schema_type} ({format_type})"
+
+    return schema_type
+
+def generate_example(schema: Dict[str, Any], swagger: Dict[str, Any]) -> Any:
+    """스키마로부터 예제 데이터 생성"""
+    if 'example' in schema:
+        return schema['example']
+
+    if 'examples' in schema:
+        return list(schema['examples'].values())[0] if schema['examples'] else None
+
+    if '$ref' in schema:
+        resolved = resolve_ref(schema['$ref'], swagger)
+        return generate_example(resolved, swagger)
+
+    schema_type = schema.get('type', 'object')
+
+    if schema_type == 'object':
+        properties = schema.get('properties', {})
+        example = {}
+        for prop_name, prop_schema in properties.items():
+            example[prop_name] = generate_example(prop_schema, swagger)
+        return example
+
+    if schema_type == 'array':
+        items = schema.get('items', {})
+        item_example = generate_example(items, swagger)
+        return [item_example] if item_example is not None else []
+
+    if schema_type == 'string':
+        if schema.get('format') == 'date-time':
+            return "2025-01-01T00:00:00Z"
+        if schema.get('format') == 'date':
+            return "2025-01-01"
+        if 'enum' in schema:
+            return schema['enum'][0]
+        return "string"
+
+    if schema_type == 'integer':
+        return 1
+
+    if schema_type == 'number':
+        return 1.0
+
+    if schema_type == 'boolean':
+        return True
+
+    return None
+
+def convert_to_markdown(swagger: Dict[str, Any], base_url: str) -> str:
+    """Swagger JSON을 Markdown으로 변환"""
+    info = swagger.get('info', {})
+    title = info.get('title', 'API Documentation')
+    version = info.get('version', '1.0.0')
+    description = info.get('description', '')
+
+    md = f"""# {title} API 문서
+
+> Generated from Swagger/OpenAPI
+> Version: {version}
+> Generated Date: {datetime.now().strftime('%Y-%m-%d')}
+
+---
+
+## 📋 목차
+
+- [개요](#개요)
+- [서버 정보](#서버-정보)
+- [인증](#인증)
+- [API 엔드포인트](#api-엔드포인트)
+- [데이터 모델](#데이터-모델)
+- [에러 코드](#에러-코드)
+
+---
+
+## 개요
+
+**서비스명**: {title}
+**버전**: {version}
+**설명**: {description if description else 'No description provided'}
+
+---
+
+## 서버 정보
+
+**Base URL**: `{base_url}`
+
+"""
+
+    # 인증 정보
+    security_schemes = {}
+    if 'components' in swagger and 'securitySchemes' in swagger['components']:
+        security_schemes = swagger['components']['securitySchemes']
+    elif 'securityDefinitions' in swagger:
+        security_schemes = swagger['securityDefinitions']
+
+    if security_schemes:
+        md += "---\n\n## 인증\n\n"
+        for scheme_name, scheme_def in security_schemes.items():
+            scheme_type = scheme_def.get('type', '')
+            if scheme_type == 'http' and scheme_def.get('scheme') == 'bearer':
+                md += f"""### Bearer Token
+
+이 API는 Bearer Token 인증을 사용합니다.
+
+**Header**:
+```
+Authorization: Bearer {{token}}
+```
+
+**Example**:
+```bash
+curl -X GET "{base_url}/api/endpoint" \\
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+"""
+            elif scheme_type == 'apiKey':
+                key_name = scheme_def.get('name', 'X-API-Key')
+                in_location = scheme_def.get('in', 'header')
+                md += f"""### API Key
+
+**{key_name}** ({in_location})
+
+**Example**:
+```bash
+curl -X GET "{base_url}/api/endpoint" \\
+  -H "{key_name}: your-api-key"
+```
+
+"""
+
+    # API 엔드포인트
+    md += "---\n\n## API 엔드포인트\n\n"
+
+    paths = swagger.get('paths', {})
+
+    # 태그별로 그룹핑
+    endpoints_by_tag = {}
+    for path, path_item in paths.items():
+        for method, operation in path_item.items():
+            if method.upper() not in ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']:
+                continue
+
+            tags = operation.get('tags', ['Default'])
+            tag = tags[0] if tags else 'Default'
+
+            if tag not in endpoints_by_tag:
+                endpoints_by_tag[tag] = []
+
+            endpoints_by_tag[tag].append({
+                'path': path,
+                'method': method.upper(),
+                'operation': operation
+            })
+
+    # 태그별로 문서 생성
+    for tag, endpoints in sorted(endpoints_by_tag.items()):
+        md += f"### {tag}\n\n"
+
+        for endpoint in endpoints:
+            path = endpoint['path']
+            method = endpoint['method']
+            operation = endpoint['operation']
+
+            summary = operation.get('summary', '')
+            description_text = operation.get('description', '')
+
+            md += f"#### `{method} {path}`\n\n"
+
+            if summary:
+                md += f"{summary}\n\n"
+
+            if description_text:
+                md += f"**Description**: {description_text}\n\n"
+
+            # Parameters
+            parameters = operation.get('parameters', [])
+            if parameters:
+                md += "**Parameters**:\n\n"
+                md += "| Name | In | Type | Required | Description |\n"
+                md += "|------|-----|------|----------|-------------|\n"
+
+                for param in parameters:
+                    name = param.get('name', '')
+                    in_location = param.get('in', '')
+                    required = '✅' if param.get('required', False) else '❌'
+                    param_description = param.get('description', '')
+
+                    param_schema = param.get('schema', {})
+                    param_type = get_schema_type(param_schema, swagger)
+
+                    md += f"| {name} | {in_location} | {param_type} | {required} | {param_description} |\n"
+
+                md += "\n"
+
+            # Request Body
+            request_body = operation.get('requestBody', {})
+            if request_body:
+                content = request_body.get('content', {})
+                if 'application/json' in content:
+                    schema = content['application/json'].get('schema', {})
+                    example = generate_example(schema, swagger)
+
+                    md += "**Request Body**:\n\n"
+                    md += "```json\n"
+                    md += json.dumps(example, indent=2, ensure_ascii=False)
+                    md += "\n```\n\n"
+
+            # Responses
+            responses = operation.get('responses', {})
+            if responses:
+                md += "**Responses**:\n\n"
+
+                for status_code, response in sorted(responses.items()):
+                    response_description = response.get('description', '')
+                    md += f"- **{status_code}** {response_description}\n\n"
+
+                    content = response.get('content', {})
+                    if 'application/json' in content:
+                        schema = content['application/json'].get('schema', {})
+                        example = generate_example(schema, swagger)
+
+                        md += "  ```json\n"
+                        md += "  " + json.dumps(example, indent=2, ensure_ascii=False).replace("\n", "\n  ")
+                        md += "\n  ```\n\n"
+
+            md += "---\n\n"
+
+    # 데이터 모델
+    md += "## 데이터 모델\n\n"
+
+    schemas = {}
+    if 'components' in swagger and 'schemas' in swagger['components']:
+        schemas = swagger['components']['schemas']
+    elif 'definitions' in swagger:
+        schemas = swagger['definitions']
+
+    for schema_name, schema_def in sorted(schemas.items()):
+        md += f"### {schema_name}\n\n"
+
+        description_text = schema_def.get('description', '')
+        if description_text:
+            md += f"{description_text}\n\n"
+
+        example = generate_example(schema_def, swagger)
+        md += "```json\n"
+        md += json.dumps(example, indent=2, ensure_ascii=False)
+        md += "\n```\n\n"
+
+        properties = schema_def.get('properties', {})
+        required_fields = schema_def.get('required', [])
+
+        if properties:
+            md += "**Properties**:\n\n"
+            md += "| Field | Type | Required | Description |\n"
+            md += "|-------|------|----------|-------------|\n"
+
+            for prop_name, prop_schema in properties.items():
+                prop_type = get_schema_type(prop_schema, swagger)
+                is_required = '✅' if prop_name in required_fields else '❌'
+                prop_description = prop_schema.get('description', '')
+
+                md += f"| {prop_name} | {prop_type} | {is_required} | {prop_description} |\n"
+
+            md += "\n"
+
+        md += "---\n\n"
+
+    # 에러 코드
+    md += """## 에러 코드
+
+### 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 |
+| 500 | Internal Server Error | Server error |
+
+---
+
+## 링크
+
+- **Swagger UI**: {base_url.replace('/v3/api-docs', '/swagger-ui.html')}
+- **API Docs JSON**: {base_url}
+
+---
+
+> 📝 이 문서는 Swagger/OpenAPI 명세로부터 자동 생성되었습니다.
+> 마지막 업데이트: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+"""
+
+    return md
+
+def main():
+    """메인 함수"""
+    if len(sys.argv) < 2:
+        print("Usage: python swagger-to-markdown.py <swagger_url> [output_file]")
+        print("Example: python swagger-to-markdown.py http://localhost:8080/v3/api-docs")
+        sys.exit(1)
+
+    swagger_url = sys.argv[1]
+    output_file = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"🔍 Fetching Swagger docs from: {swagger_url}")
+    swagger = fetch_swagger(swagger_url)
+
+    base_url = get_base_url(swagger)
+    if not base_url:
+        # URL에서 base path 추출
+        parsed = urlparse(swagger_url)
+        base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+    print(f"📝 Generating Markdown documentation...")
+    markdown = convert_to_markdown(swagger, base_url)
+
+    if output_file:
+        with open(output_file, 'w', encoding='utf-8') as f:
+            f.write(markdown)
+        print(f"✅ Documentation saved to: {output_file}")
+    else:
+        print(markdown)
+
+if __name__ == '__main__':
+    main()