FastAPI는 어떻게 자동 문서를 생성합니까?

Question

Accepted Answer

FastAPI는 코드로부터 **대화형 API 문서를 자동으로 생성**합니다. 라우트, 매개변수, Pydantic 모델이 OpenAPI 스키마(schema)로 변환되고, 이것이 두 개의 탐색 가능한 문서 UI(Swagger UI와 ReDoc)를 아무 노력 없이 구동합니다.

## 문서를 무료로 얻습니다

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → 엔드포인트 설명
    return item
```

타입이 지정된 엔드포인트와 모델을 작성하기만 하면 FastAPI가 완전한 문서를 생성합니다. 별도로 작성하거나 유지보수할 문서 파일이 없습니다.

## 두 가지 내장 문서 UI

```text
/docs   → Swagger UI — 대화형: 엔드포인트를 탐색하고 브라우저에서 직접 테스트
          (매개변수 입력, 요청 전송, 응답 실시간 확인)
/redoc  → ReDoc — 깔끔하고 읽기 쉬운 레퍼런스 스타일 뷰
/openapi.json → 원시 OpenAPI 스키마 (클라이언트 SDK 생성 등에 사용 가능)
```

`/docs`를 방문하면 모든 엔드포인트를 탐색하고, 필수 매개변수와 응답 형태를 확인하며, 브라우저에서 직접 **실제 요청을 보낼** 수 있습니다. 개발 중이나 API 사용자에게 매우 유용합니다.

## 문서 내용은 어디서 오는가

```text
라우트 데코레이터 → 경로, HTTP 메서드, tags, summaries
타입 힌트         → 매개변수 타입, 필수/선택
Pydantic 모델     → 요청/응답 schema, 필드 제약 조건 및 설명
Docstring         → 엔드포인트 설명
Field(..., description=, example=) → 필드별 문서 및 예시
```

모든 것이 이미 작성한 코드로부터 파생되므로, 문서는 자동으로 구현과 **동기화 상태**를 유지합니다.

## 문서 풍부하게 만들기

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## 왜 중요한가

자동 대화형 문서는 FastAPI의 가장 호평받는 기능 중 하나이며 인기의 주된 이유입니다.

문서가 코드(라우트, 타입 힌트, Pydantic 모델, docstring)로부터 직접 생성되기 때문에, 항상 실제 구현과 **동기화**되어 있습니다. 손으로 작성한 문서를 괴롭히는 만성적인 문제—문서가 최신 상태에서 벗어나는 것—를 제거합니다.

대화형 Swagger UI(`/docs`)는 개발자와 API 사용자가 브라우저에서 **엔드포인트를 직접 탐색하고 테스트**할 수 있게 하여, 개발자 경험을 크게 향상시키고 통합 마찰을 줄입니다.

생성된 OpenAPI 스키마는 클라이언트 SDK 생성과 계약 테스트도 구동할 수 있습니다.

잘 타입이 지정된 코드를 작성하는 것만으로 전문적이고 정확한 대화형 API 문서를 사실상 무료로 얻는 것은 상당한 생산성 및 품질 이점이며, 이를 중요하고 차별화된 FastAPI 역량으로 만듭니다.