# MCP API 문서 자동화 시스템

Django REST Framework ViewSet을 자동으로 분석하여 OpenAPI 3.0 스펙의 API 문서를 생성하는 완전 자동화 시스템입니다.

## 📋 목차

- [프로젝트 개요](#프로젝트-개요)
- [시스템 아키텍처](#시스템-아키텍처)
- [주요 기능](#주요-기능)
- [기술 스택](#기술-스택)
- [프로젝트 구조](#프로젝트-구조)
- [로컬 환경 설정](#로컬-환경-설정)
- [실행 방법](#실행-방법)
- [API 사용법](#api-사용법)
- [구현 상세 내용](#구현-상세-내용)
- [테스트 방법](#테스트-방법)
- [생성된 API 문서 예시](#생성된-api-문서-예시)
- [트러블슈팅](#트러블슈팅)

## 🎯 프로젝트 개요

### 목적

- Django 프로젝트의 ViewSet을 자동으로 탐지하고 분석
- 실제 serializer 필드를 기반으로 정확한 OpenAPI 3.0 스펙 생성
- Request/Response 파라미터, 헤더, 바디 정보 완전 자동화
- Swagger UI를 통한 직관적인 API 문서 제공

### 핵심 특징

- ✅ **완전 자동화**: 수동 설정 없이 ViewSet 자동 탐지
- ✅ **정확한 스키마**: 실제 serializer 필드 1:1 반영
- ✅ **125개 엔드포인트**: 모든 ViewSet CRUD 작업 지원
- ✅ **실시간 생성**: 코드 변경 시 즉시 문서 업데이트
- ✅ **JavaScript 호환**: Swagger UI 완벽 지원

## 🏗️ 시스템 아키텍처

```
┌─────────────────┐    HTTP Request    ┌─────────────────┐
│   MCP Server    │ ──────────────────► │ Python Parser   │
│  (Spring Boot)  │                    │   (FastAPI)     │
│   Port: 8080    │                    │   Port: 8009    │
└─────────────────┘                    └─────────────────┘
         │                                       │
         │                                       │
         ▼                                       ▼
┌─────────────────┐                    ┌─────────────────┐
│   Swagger UI    │                    │ Django Project  │
│  API Docs HTML  │                    │  ViewSet Files  │
│  /api-docs/html │                    │  /shared_repos/ │
└─────────────────┘                    └─────────────────┘
```

### 컴포넌트 설명

1. **Python Parser (FastAPI)**

   - Django ViewSet 자동 탐지 및 분석
   - OpenAPI 3.0 스펙 생성
   - 실제 serializer 필드 추출

2. **MCP Server (Spring Boot)**

   - Swagger UI 제공
   - JSON API 문서 서빙
   - 프록시 역할

3. **Django Project**
   - 분석 대상 ViewSet 파일들
   - 실제 serializer 정의

## 🚀 주요 기능

### 1. ViewSet 자동 탐지

- `app/` 디렉토리 내 모든 앱 스캔
- `views.py` 또는 `views/` 폴더 내 파일 분석
- `class \w+ViewSet` 패턴 자동 발견

### 2. Serializer 필드 추출

- `serializer_class` 속성 자동 감지
- 실제 필드 타입, nullable, required 정보 추출
- 중첩 serializer 지원

### 3. OpenAPI 3.0 스펙 생성

- Request 파라미터 (쿼리, 헤더, 바디)
- Response 스키마 (상태 코드별)
- 인증 정보 (Authorization 헤더)
- Pagination, Search, Filtering 지원

### 4. CRUD 엔드포인트 자동 생성

- **GET** `/api/v1/{resource}/` - 목록 조회
- **POST** `/api/v1/{resource}/` - 생성
- **GET** `/api/v1/{resource}/{id}/` - 상세 조회
- **PUT** `/api/v1/{resource}/{id}/` - 수정
- **DELETE** `/api/v1/{resource}/{id}/` - 삭제

## 🛠️ 기술 스택

### Backend

- **Python 3.12.2**: 메인 파싱 로직
- **FastAPI**: Python Parser 서버
- **Django**: 분석 대상 프로젝트
- **Django REST Framework**: ViewSet 분석

### Frontend

- **Spring Boot**: MCP 서버
- **Swagger UI**: API 문서 인터페이스
- **Thymeleaf**: HTML 템플릿

### 개발 도구

- **Gradle**: Spring Boot 빌드
- **uvicorn**: FastAPI 서버
- **watchfiles**: 자동 리로드

## 📁 프로젝트 구조

```
mcp-docs-server-final/
├── python-parser/                    # Python Parser 서버
│   ├── main.py                      # FastAPI 서버 진입점
│   ├── src/
│   │   ├── application/             # 애플리케이션 레이어
│   │   │   └── use_cases/
│   │   │       └── generate_api_docs_use_case.py
│   │   ├── domain/                  # 도메인 레이어
│   │   │   └── entities/
│   │   │       ├── api_documentation.py
│   │   │       ├── api_endpoint.py
│   │   │       └── api_parameter.py
│   │   ├── infrastructure/          # 인프라 레이어
│   │   │   ├── generators/
│   │   │   │   └── api_documentation_generator.py
│   │   │   └── parsers/
│   │   │       └── python_parser.py
│   │   └── presentation/            # 프레젠테이션 레이어
│   │       └── controllers/
│   │           └── api_docs_controller.py
│   ├── generated_docs/              # 생성된 API 문서
│   │   └── ucms-be_api_docs.json
│   └── requirements.txt
├── shared_repos/                    # 분석 대상 Django 프로젝트
│   └── ucms-be/
│       └── app/
│           ├── account/
│           ├── revenue/
│           ├── content/
│           └── ... (기타 앱들)
├── src/                             # Spring Boot MCP 서버
│   └── main/
│       ├── java/
│       │   └── com/odk/
│       │       └── controller/
│       │           └── ApiDocsController.java
│       └── resources/
│           ├── templates/
│           │   └── swagger-viewer.html
│           └── static/
│               └── openapi/
├── build.gradle                     # Spring Boot 빌드 설정
└── docker-compose.override.yml      # Docker 설정
```

## 🔧 로컬 환경 설정

### 1. Python 환경 설정

```bash
# Python 3.12.2 설치 (pyenv 사용)
pyenv install 3.12.2
pyenv local 3.12.2

# 가상환경 생성 및 활성화
cd python-parser
python -m venv venv
source venv/bin/activate  # macOS/Linux
# 또는
venv\Scripts\activate     # Windows
```

### 2. Python 의존성 설치

```bash
cd python-parser
pip install -r requirements.txt
```

### 3. Spring Boot 환경 설정

```bash
# Java 17 이상 필요
java -version

# Gradle 빌드
./gradlew build
```

## 🚀 실행 방법

### 1. Python Parser 서버 시작

```bash
cd python-parser
python main.py
```

**서버 정보:**

- URL: `http://localhost:8009`
- 자동 리로드: 활성화
- Django 환경: 자동 설정

### 2. Spring Boot MCP 서버 시작

```bash
# 프로젝트 루트에서
./gradlew bootRun
```

**서버 정보:**

- URL: `http://localhost:8080`
- Swagger UI: `http://localhost:8080/api-docs/html`
- JSON API: `http://localhost:8080/api-docs/json`

### 3. API 문서 생성

```bash
# Python Parser 서버가 실행 중인 상태에서
curl -X POST "http://localhost:8009/api/v1/docs/generate/ucms-be?base_url=http://localhost:8009&save_to_file=true"
```

## 📖 API 사용법

### 1. API 문서 생성 엔드포인트

```http
POST /api/v1/docs/generate/{project_name}
```

**파라미터:**

- `project_name`: 프로젝트 이름 (예: ucms-be)
- `base_url`: 기본 URL (예: http://localhost:8009)
- `save_to_file`: 파일 저장 여부 (true/false)

**응답:**

```json
{
  "success": true,
  "message": "API documentation generated successfully",
  "data": {
    "endpoints_count": 125,
    "file_path": "generated_docs/ucms-be_api_docs.json"
  }
}
```

### 2. 생성된 문서 확인

- **Swagger UI**: `http://localhost:8080/api-docs/html`
- **JSON 파일**: `http://localhost:8080/api-docs/json`
- **로컬 파일**: `python-parser/generated_docs/ucms-be_api_docs.json`

## 🔍 구현 상세 내용

### 1. ViewSet 자동 탐지 로직

```python
def discover_viewsets(django_app_path: str) -> List[Tuple[str, str]]:
    """
    Django 앱 디렉토리에서 ViewSet 클래스 자동 탐지

    Args:
        django_app_path: Django 앱 경로

    Returns:
        List[Tuple[앱명.ViewSet명, URL경로]]
    """
    viewsets = []

    # app/ 디렉토리 내 모든 앱 스캔
    for app_dir in os.listdir(django_app_path):
        app_path = os.path.join(django_app_path, app_dir)

        if os.path.isdir(app_path):
            # views.py 파일 확인
            views_file = os.path.join(app_path, "views.py")
            if os.path.exists(views_file):
                viewsets.extend(extract_viewsets_from_file(views_file, app_dir))

            # views/ 폴더 확인
            views_dir = os.path.join(app_path, "views")
            if os.path.isdir(views_dir):
                for file in os.listdir(views_dir):
                    if file.endswith(".py"):
                        file_path = os.path.join(views_dir, file)
                        viewsets.extend(extract_viewsets_from_file(file_path, f"{app_dir}/views/{file[:-3]}"))

    return viewsets
```

### 2. Serializer 필드 추출 로직

```python
def extract_serializer_from_viewset(viewset_class, viewset_name: str) -> Dict[str, Any]:
    """
    ViewSet에서 실제 사용하는 serializer 필드 추출

    Args:
        viewset_class: ViewSet 클래스
        viewset_name: ViewSet 이름

    Returns:
        Dict[str, Any]: 필드 정보 딕셔너리
    """
    try:
        # 1. serializer_class 속성 확인
        if hasattr(viewset_class, 'serializer_class'):
            serializer_class = viewset_class.serializer_class
            return extract_serializer_fields(serializer_class)

        # 2. get_serializer_class 메서드 확인
        if hasattr(viewset_class, 'get_serializer_class'):
            serializer_class = viewset_class.get_serializer_class()
            return extract_serializer_fields(serializer_class)

        # 3. 소스 코드 분석으로 serializer 패턴 찾기
        return extract_serializer_from_source(viewset_class, viewset_name)

    except Exception as e:
        print(f"[문서 자동화] {viewset_name}에서 serializer 필드 추출 실패: {e}")
        return None
```

### 3. OpenAPI 스펙 생성 로직

```python
def generate_openapi_for_viewset(
    viewset_name: str,
    file_path: str,
    base_url: str,
    model_name: str = None,
) -> List[ApiEndpoint]:
    """
    ViewSet에서 OpenAPI 엔드포인트 생성

    Args:
        viewset_name: ViewSet 클래스명
        file_path: ViewSet 파일 경로
        base_url: 기본 URL
        model_name: 모델명 (선택사항)

    Returns:
        List[ApiEndpoint]: 생성된 엔드포인트 목록
    """
    # 1. ViewSet 클래스 import
    viewset_class = import_viewset_class(file_path, viewset_name)

    # 2. Serializer 필드 추출
    serializer_fields = extract_serializer_from_viewset(viewset_class, viewset_name)

    # 3. URL 경로 생성
    resource_name = model_name or viewset_name.replace('ViewSet', '').lower()
    base_path = f"/api/v1/{resource_name}/"

    # 4. CRUD 엔드포인트 생성
    endpoints = []

    # GET /api/v1/{resource}/ - 목록 조회
    endpoints.append(ApiEndpoint(
        path=base_path,
        method=HttpMethod.GET,
        summary=f"Get {resource_name} list",
        description=f"Retrieve a list of {resource_name}",
        parameters=generate_list_parameters(),
        responses=generate_list_responses(serializer_fields)
    ))

    # POST /api/v1/{resource}/ - 생성
    endpoints.append(ApiEndpoint(
        path=base_path,
        method=HttpMethod.POST,
        summary=f"Create {resource_name}",
        description=f"Create a new {resource_name}",
        parameters=generate_create_parameters(),
        request_body=generate_request_body(serializer_fields),
        responses=generate_create_responses(serializer_fields)
    ))

    # 기타 CRUD 엔드포인트들...

    return endpoints
```

## 🧪 테스트 방법

### 1. 단위 테스트

```bash
cd python-parser
python -m pytest tests/
```

### 2. 통합 테스트

```bash
# 1. Python Parser 서버 시작
cd python-parser
python main.py

# 2. API 문서 생성 요청
curl -X POST "http://localhost:8009/api/v1/docs/generate/ucms-be?base_url=http://localhost:8009&save_to_file=true"

# 3. 생성된 파일 확인
ls -la generated_docs/
cat generated_docs/ucms-be_api_docs.json | jq '.paths | keys | length'
```

### 3. Swagger UI 테스트

```bash
# 1. Spring Boot 서버 시작
./gradlew bootRun

# 2. 브라우저에서 확인
open http://localhost:8080/api-docs/html
```

### 4. 엔드포인트별 테스트

```bash
# Revenue API 테스트
curl -X GET "http://localhost:8080/api-docs/json" | jq '.paths | keys | grep revenue'

# AdminUser API 테스트
curl -X GET "http://localhost:8080/api-docs/json" | jq '.paths | keys | grep adminuser'
```

## 📊 생성된 API 문서 예시

### 1. Revenue API 엔드포인트

```json
{
  "/api/v1/revenues/": {
    "get": {
      "summary": "Get revenues list",
      "description": "Retrieve a list of revenues",
      "tags": ["revenue"],
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "required": true,
          "description": "Bearer token for authentication",
          "schema": { "type": "string" }
        },
        {
          "name": "page",
          "in": "query",
          "required": false,
          "description": "Page number for pagination",
          "schema": { "type": "integer" }
        }
      ],
      "responses": {
        "200": {
          "description": "Successful response",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": { "type": "integer" },
                  "amount": { "type": "number", "format": "decimal" },
                  "currency": { "type": "string" },
                  "created_at": { "type": "string", "format": "date-time" },
                  "updated_at": { "type": "string", "format": "date-time" }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

### 2. 생성된 엔드포인트 통계

- **총 엔드포인트**: 125개
- **ViewSet 개수**: 25개
- **주요 ViewSet**:
  - Revenue (16개 필드)
  - RevenueShare (16개 필드)
  - AdminUser (8개 필드)
  - UserActionHistory (12개 필드)
  - VideoSource (23개 필드)
  - Series (18개 필드)
  - Content (다양한 필드)
  - 기타 모든 ViewSet

## 🔧 트러블슈팅

### 1. Django 환경 설정 문제

**문제**: `DJANGO_SETTINGS_MODULE` 미설정

```bash
Error: No module named 'django'
```

**해결책**:

```python
def setup_django_environment(django_app_path: str):
    """Django 환경 설정"""
    import os
    import sys
    import django

    # Django 설정 모듈 환경변수 설정
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

    # 프로젝트 및 앱 경로를 Python 경로에 추가
    project_root = os.path.dirname(django_app_path)
    sys.path.insert(0, project_root)
    sys.path.insert(0, django_app_path)

    # Django 설정
    django.setup()
```

### 2. ViewSet Import 실패

**문제**: 상대 import 오류

```bash
Error: attempted relative import with no known parent package
```

**해결책**:

```python
def import_viewset_class(file_path: str, viewset_name: str):
    """ViewSet 클래스 import"""
    try:
        # 1. 직접 import 시도
        module_name = get_module_name_from_path(file_path)
        module = importlib.import_module(module_name)
        return getattr(module, viewset_name)
    except ImportError:
        # 2. fallback: 파일 파싱
        return parse_viewset_from_file(file_path, viewset_name)
```

### 3. Serializer 필드 추출 실패

**문제**: `cached_property` 오류

```bash
Error: 'cached_property' object has no attribute 'get_fields'
```

**해결책**:

```python
def extract_serializer_fields(serializer_class):
    """Serializer 필드 추출"""
    try:
        # Serializer 인스턴스 생성
        serializer = serializer_class()

        # fields 속성에 안전하게 접근
        if hasattr(serializer, 'fields'):
            fields = serializer.fields
            return {name: extract_field_schema(field) for name, field in fields.items()}
    except Exception as e:
        print(f"Serializer 필드 추출 실패: {e}")
        return None
```

### 4. JavaScript 호환성 문제

**문제**: Swagger UI에서 `Object.keys()` 오류

```javascript
TypeError: Cannot convert undefined or null to object
```

**해결책**:

```python
def to_openapi_dict(self) -> Dict[str, Any]:
    """OpenAPI 3.0 형식으로 변환"""
    endpoint_dict = {
        "summary": endpoint.summary,
        "description": endpoint.description,
        "tags": endpoint.tags,
        "deprecated": endpoint.deprecated,
        "parameters": [...],
    }

    # null 값 제거로 JavaScript 호환성 확보
    if endpoint.request_body is not None:
        endpoint_dict["requestBody"] = endpoint.request_body

    if endpoint.responses is not None:
        endpoint_dict["responses"] = endpoint.responses

    return endpoint_dict
```

## 📈 성능 최적화

### 1. 캐싱 전략

- ViewSet 클래스 import 결과 캐싱
- Serializer 필드 추출 결과 캐싱
- 파일 변경 감지로 부분 업데이트

### 2. 병렬 처리

- 여러 ViewSet 동시 분석
- 파일 I/O 비동기 처리

### 3. 메모리 최적화

- 불필요한 객체 생성 방지
- 가비지 컬렉션 최적화

## 🔮 향후 개선 계획

### 1. 기능 확장

- [ ] GraphQL 스키마 생성 지원
- [ ] API 버전 관리
- [ ] 커스텀 필터링/정렬 지원
- [ ] API 테스트 코드 자동 생성

### 2. 성능 개선

- [ ] Redis 캐싱 도입
- [ ] 배치 처리 최적화
- [ ] 메모리 사용량 모니터링

### 3. 사용성 개선

- [ ] 웹 인터페이스 추가
- [ ] 실시간 문서 업데이트
- [ ] API 문서 버전 관리

## 📞 지원 및 문의

프로젝트 관련 문의사항이나 버그 리포트는 이슈를 통해 제출해 주세요.

---

**개발자**: AI Assistant  
**최종 업데이트**: 2024년 12월  
**버전**: 1.0.0