muno-claude-plugin 1.8.0 → 1.10.0

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()