API 문서화: drf-spectacular로 OpenAPI 3.0(Swagger) 문서 자동 생성하기

drf-spectacular를 사용하여 Django REST Framework에서 OpenAPI 3.0 스키마를 자동 생성하고, 코드와 문서 간의 불일치를 방지하며 개발 생산성을 향상시키는 방법

기본 설정 및 연동

패키지 설치

pip install drf-spectacular

settings.py 설정

• INSTALLED_APPS에 drf_spectacular 추가

• REST_FRAMEWORK에 DEFAULT_SCHEMA_CLASS 설정

• SPECTACULAR_SETTINGS로 API 문서 기본 정보 정의

URL 설정

• 스키마 다운로드: /api/schema/

• Swagger UI: /api/swagger/

• ReDoc: /api/redoc/

@extend_schema 데코레이터 활용

기본 파라미터

• tags: API 그룹화

• summary: 한 줄 요약

• description: 상세 설명 (마크다운 지원)

• request: 요청 Body 스키마

• responses: 응답 스키마 (상태 코드별)

• parameters: 쿼리/경로 파라미터

ViewSet 전체 적용

• @extend_schema_view로 각 action별 문서화 한 번에 정의

• 읽기/쓰기 Serializer 분리로 명확성 증대

Serializer 문서화 강화

SerializerMethodField 타입 명시

• @extend_schema_field로 정확한 반환 타입 지정

• OpenApiTypes.STR, OpenApiTypes.BOOL 등 활용

응답 예시 추가

• OpenApiExample로 실제 응답 구조 제공

• 성공/실패 케이스별 예시 포함

인증 정보 포함

인증 스킴 정의

• SPECTACULAR_SETTINGS의 SECURITY_DEFINITIONS에 Bearer Token, API Key 등 설정

• Swagger UI "Authorize" 버튼 활성화

View별 인증 설정

• security 파라미터로 특정 API의 인증 방식 오버라이드

• 실제 authentication_classes와 일치시키기

Enum과 TypedDict 활용

Enum 사용

• 모델의 choices 필드를 TextChoices로 정의

• Swagger UI에서 드롭다운으로 자동 표시

TypedDict 활용

• 구조화된 딕셔너리 응답의 스키마 정의

• Serializer 없이 명확한 응답 구조 문서화

실무 팁

• 문서도 코드로 관리하여 Git 버전 관리 및 코드 리뷰 포함

• 기본 자동 생성 후 필요한 부분부터 점진적 개선

• @action 데코레이터 적극 활용

• 에러 응답(4xx, 5xx)도 충실히 문서화

• 프로덕션에서는 정적 스키마 파일 생성 고려