"이 엔드포인트 뭐 하는 거예요?"

API를 만들었다. 5개 엔드포인트. 프론트엔드 개발자가 물어본다.

"/api/diagnose에 POST 보내면 되나요?" "body에 뭘 넣어야 하나요?" "응답 형식이 어떻게 되나요?"

매번 Slack으로 대답한다. 일주일 후, 같은 질문이 또 온다.

"아까 알려주셨는데 기억이 안 나서요..."

API 문서가 없으면, 개발자 = 살아있는 문서가 된다.

---

FastAPI가 해결해준다

FastAPI의 최대 장점: 코드 = 문서.

# 이 코드를 작성하면
@app.post("/api/diagnose", response_model=DiagnosisResponse)
async def diagnose_error(request: DiagnosisRequest):
    """
    에러코드 기반 설비 진단

    에러코드를 입력하면 원인 분석 및 조치 방법을 반환합니다.
    Knowledge Graph와 RAG를 활용하여 정확한 진단을 제공합니다.
    """
    ...

# 이 문서가 자동으로 생성된다

POST /api/diagnose
├── Summary: 에러코드 기반 설비 진단
├── Description: 에러코드를 입력하면...
├── Request Body: DiagnosisRequest (자동)
├── Response: DiagnosisResponse (자동)
└── Example: 자동 생성

접속: http://localhost:8000/docs     (Swagger UI)
접속: http://localhost:8000/redoc    (ReDoc)

---

Pydantic 모델이 핵심이다

from pydantic import BaseModel, Field
from typing import Optional, List
from enum import Enum

class ErrorSeverity(str, Enum):
    """에러 심각도"""
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class DiagnosisRequest(BaseModel):
    """에러 진단 요청"""
    error_code: str = Field(
        description="설비 에러코드 (예: E-CNC-001)",
        example="E-CNC-001"
    )
    equipment_id: Optional[str] = Field(
        None,
        description="설비 ID (지정 시 해당 설비 이력 참조)",
        example="CNC-M01-LINE3"
    )
    include_history: bool = Field(
        default=True,
        description="과거 고장 이력 포함 여부"
    )

class ActionStep(BaseModel):
    """조치 단계"""
    step: int = Field(description="단계 번호")
    action: str = Field(description="수행할 조치")
    caution: Optional[str] = Field(
        None,
        description="주의사항"
    )

class DiagnosisResponse(BaseModel):
    """에러 진단 응답"""
    error_code: str = Field(description="입력된 에러코드")
    diagnosis: str = Field(description="진단 결과")
    severity: ErrorSeverity = Field(description="심각도")
    root_cause: str = Field(description="근본 원인")
    actions: List[ActionStep] = Field(description="조치 단계")
    sources: List[str] = Field(
        default=[],
        description="참조 문서 목록"
    )
    confidence: float = Field(
        description="진단 신뢰도 (0.0~1.0)",
        ge=0.0, le=1.0
    )

---

Field 하나가 문서 품질을 결정한다

Field 속성	역할	효과
description	API 문서에 설명 표시	개발자가 바로 이해
example	테스트용 예시 자동 생성	Try it out에서 바로 실행
ge, le	값 범위 제한 + 문서 표시	잘못된 요청 방지
default	기본값 + 문서 표시	Optional 필드 명확화

---

Swagger vs ReDoc vs Postman

도구	장점	단점	추천
Swagger UI (/docs)	바로 테스트 가능	복잡한 API에서 느림	개발 중 테스트
ReDoc (/redoc)	가독성 최고	테스트 불가	공유용 문서
Postman	팀 협업, 자동 테스트	별도 설정 필요	팀 개발

추천 조합: 개발 중 Swagger + 공유는 ReDoc + 팀 협업은 Postman

---

핵심 정리

1. FastAPI의 코드 = 문서 철학을 최대한 활용
2. Pydantic Field의 description, example이 문서 품질을 결정
3. Enum으로 허용 값을 명시하면 문서가 더 명확
4. /docs(테스트) + /redoc(공유) 조합이 최적