콘텐츠로 이동

FastAPI OpenAPI 자동 문서화

개요

API를 만들면 엔드포인트 명세를 문서로 정리하는 일이 늘 뒤따라요. 요청·응답 모델이 바뀔 때마다 문서를 손으로 고치면 금방 어긋나죠. FastAPI는 이런 수고를 타입 힌트 기반 설계로 없애는데, 그 결과로 문서화도 자동으로 따라옵니다. FastAPI는 OpenAPI 표준을 기반으로 만들어져서, 경로 동작·파라미터·요청 본문·보안 등이 자동으로 문서화되고 인터랙티브 문서 UI까지 기본 제공돼요.

핵심 개념

오픈 표준에 기반

FastAPI는 OpenAPI를 기반으로 설계됐어요. 경로 동작, 파라미터, 요청 본문, 보안 등이 모두 OpenAPI로 선언되고, 데이터 모델 문서는 JSON Schema로 자동 만들어집니다(OpenAPI 자체가 JSON Schema에 기반하죠). 단순히 겉에 얹은 계층이 아니라 표준을 깊이 연구해 그 위에 지은 구조라서, 이 명세로 여러 언어의 자동 클라이언트 코드 생성까지 가능해요.

인터랙티브 문서 기본 제공

OpenAPI 기반이니 여러 문서 UI가 쓸 수 있는데, 기본으로 2개가 포함됩니다.

  • Swagger UI — 브라우저에서 인터랙티브하게 API를 호출·테스트해 볼 수 있어요.
  • ReDoc — 대안적인 API 문서 UI.

두 UI 모두 요청·응답 스키마를 보여주고 바로 실행해 볼 수 있어서, 개발 중 협업이나 클라이언트 개발에 유용해요.

타입 힌트가 곧 스키마

FastAPI는 표준 Python 타입 선언(Pydantic 덕분)을 그대로 스키마로 씁니다. 함수 파라미터에 name: str, age: int처럼 타입을 적으면, FastAPI가 그걸 읽어 요청 검증과 문서화를 동시에 해요. 별도의 새로운 문법을 배울 필요 없이 표준 현대 Python만 쓰면 됩니다.

from datetime import date
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    joined: date

검증·에디터 지원

타입 선언에 따라 요청 본문이 스키마와 맞는지 검증되고, 잘못된 타입의 요청은 422로 반환돼요. 프레임워크 전체가 자동 완성과 에디터 지원을 염두에 두고 설계돼서, 중첩된 JSON 본문 안의 키까지 자동 완성이 도와주는 경우도 있습니다.

관례대로 동작

모든 것에 합리적인 기본값이 있고 필요하면 세부 파라미터로 조정할 수 있어요. 기본 상태로는 그냥 "잘 동작"하도록 설계됐죠.

실제 적용 (데이터스케쳐스 관점)

FastAPI를 쓰는 AI·자동화 API는 OpenAPI 자동 문서화를 계약 관리에 활용해요.

  • 계약 명세 자동화 — 요청·응답 모델을 타입으로 정의하면 Swagger/ReDoc이 자동 갱신되어 클라이언트와 최신 계약을 유지해요.
  • 모델 서빙 앞단 — 외부에 제공하는 모델 서빙 API의 스키마를 엄격히 검증하고 OpenAPI 계약으로 노출합니다.
  • 클라이언트 코드 생성 — OpenAPI 명세를 기반으로 여러 언어의 클라이언트를 자동 생성해 연동 비용을 줄여요.

더 알아보기