제6.4장: API 문서화

학습 시간: 30분

1. API 문서화가 왜 필요한가요?

버튼에 아무런 설명도 없는 복잡한 우주선 제어판을 받았다고 상상해 보세요. 불을 켜는 대신 비상 탈출 장치를 작동시킬 위험을 감수하며 무작위로 버튼을 누르게 될 것입니다. API 문서는 바로 이러한 설명과 지침입니다.

좋은 문서화는:

시간을 절약합니다: 개발자가 어떤 엔드포인트가 있고, 어떤 매개변수를 받으며, 무엇을 반환하는지 추측할 필요가 없습니다.
오류를 줄입니다: 명확한 데이터 형식 및 오류 코드 설명은 API의 잘못된 사용을 방지하는 데 도움이 됩니다.
통합을 간소화합니다: 프론트엔드 팀은 문서를 계약서처럼 활용하여 백엔드 팀과 병렬로 작업할 수 있습니다.
당신의 유산입니다: 6개월 후에 프로젝트로 돌아왔을 때 스스로에게 고맙다고 말하게 될 것입니다.

💡 우주 비유:

API = 복잡한 우주 정거장 제어 시스템.

API 문서화 = 우주 비행사를 위한 매뉴얼. 여기에는 다음이 설명되어 있습니다:

에어록을 열기 위해 어떤 명령(엔드포인트)을 보낼지.

생명 유지 시스템을 설정하기 위해 어떤 매개변수(요청 본문)를 전달할지.

응답으로 어떤 신호(API 응답)를 기대할지.

2. FastAPI에서의 문서화: 자동 마법

FastAPI는 문서화를 놀랍도록 간단하게 만듭니다. FastAPI는 OpenAPI 및 Swagger UI 표준을 사용하여 코드를 기반으로 대화형 문서를 자동으로 생성합니다.

단계 1: 애플리케이션에 메타데이터 추가

main.py 파일에 문서에 표시될 설명을 추가할 수 있습니다.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (FastAPI 코드)

app = FastAPI(
    title="SpaceAPI",
    description="""
은하계 탐사를 위한 API. 🚀

다음과 같은 작업을 할 수 있습니다:
* **행성 보기**.
* **새로운 행성 추가** (인증 필요).
    """,
    version="1.0.0",
    contact={
        "name": "관제 센터 수석 엔지니어",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

단계 2: 모델 및 엔드포인트 설명

Pydantic 모델과 엔드포인트 매개변수를 자세히 설명할수록 문서가 더 좋아집니다.

# Pydantic 모델 파일 또는 main.py에서

class PlanetBase(BaseModel):
    name: str = Field(..., example="지구", description="행성 이름")
    description: str = Field(..., example="다양한 생명체가 있는 푸른 행성", description="간략한 설명")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # 또는 Pydantic v2에서는 from_attributes = True

# 라우트 파일에서
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="모든 행성 목록 가져오기",
    description="(향후) 페이지네이션과 함께 알려진 모든 행성 목록을 반환합니다."
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="새 행성 생성",
    responses={
        401: {"description": "사용자 인증되지 않음"},
        422: {"description": "데이터 유효성 검사 오류"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...

Field(..., example="..."): 문서에 예시를 추가합니다.
summary: 엔드포인트의 간략한 설명.
description: 자세한 설명.
responses: 성공적인 응답을 제외한 가능한 응답 코드 설명.

단계 3: 브라우저에서 문서 열기

FastAPI 서버를 시작하고 두 개의 마법 같은 URL을 엽니다:

http://127.0.0.1:8000/docs — Swagger UI 대화형 문서를 엽니다. 여기에서 엔드포인트를 읽을 수 있을 뿐만 아니라 브라우저에서 직접 테스트할 수도 있습니다!
http://127.0.0.1:8000/redoc — ReDoc의 대체 문서 보기를 엽니다. 이 보기는 상호 작용성이 떨어지지만 종종 더 읽기 쉽습니다.

3. Laravel에서의 문서화: 서드파티 패키지 사용

FastAPI와 달리 Laravel은 "기본적으로" 문서를 생성하지 않습니다. 그러나 코드를 분석하여 이를 수행하는 훌륭한 패키지들이 있습니다. 가장 인기 있는 것은 Scribe입니다.

단계 1: Scribe 설치

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

단계 2: DocBlock을 사용하여 엔드포인트 설명

Scribe는 컨트롤러 메서드 위에 있는 PHP DocBlock(댓글 형식: /** ... */)을 읽습니다.

app/Http/Controllers/PlanetController.php를 엽니다:

// app/Http/Controllers/PlanetController.php

/**
 * @group 행성
 * 행성 관리를 위한 API
 */
class PlanetController extends Controller
{
    /**
     * 행성 목록 가져오기
     *
     * 은하계의 모든 행성의 페이지네이션된 목록을 반환합니다.
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * 새 행성 생성
     *
     * @authenticated
     *
     * @bodyParam name string required 행성 이름. Example: Kepler-186f
     * @bodyParam description string required 행성 설명.
     * @bodyParam size_km integer required 직경 (킬로미터). Example: 14000
     * @bodyParam is_habitable boolean 행성이 거주 가능한지 여부. Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "다른 별의 거주 가능 구역에서 확인된 최초의 지구 크기 행성입니다.",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... 기타 다른 메서드도 마찬가지
}

Scribe 주요 태그:

@group: 엔드포인트를 그룹화합니다.
@unauthenticated / @authenticated: 토큰이 필요한지 여부를 나타냅니다.
@bodyParam: 요청 본문의 매개변수를 설명합니다.
@response: 성공적인 응답 예시.

단계 3: 문서 생성 및 보기

DocBlock을 변경할 때마다 다음 명령을 실행합니다:

php artisan scribe:generate

Scribe는 문서가 포함된 정적 HTML 페이지를 생성합니다. 다음 주소로 엽니다: http://your-app-url/docs.

정리 퀴즈

🚀 장 요약:

당신은 "블랙박스"였던 API를 이해하기 쉽고 편리한 도구로 바꾸어 전문적인 문서를 생성했습니다.

✅ API 문서화의 중요성을 이해했습니다.
🪄 FastAPI에서 문서 자동 생성 사용법을 익혔습니다.
⚙️ Laravel에서 API를 문서화하기 위한 Scribe 패키지의 기초를 익혔습니다.
🛰️ 좋은 문서화가 모든 개발자에게 최고의 조력자임을 확신했습니다.

이제 당신의 API는 작동하고 보호될 뿐만 아니라, 다른 팀원들이 사용하기에 완전히 준비되었습니다. 마지막이자 가장 중요한 단계는 최종 보안 검사입니다.

📌 확인:

FastAPI의 경우: 브라우저에서 /docs를 열고 Swagger UI 인터페이스에서 직접 행성 목록에 대한 GET 요청을 시도해 보세요.

Laravel의 경우: php artisan scribe:generate를 실행하고 /docs를 여세요. 엔드포인트가 그룹화되어 있고, store 메서드에 파라미터 설명이 있는지 확인하세요.