🚩[3단계-1] Django 5.2 + DRF + Swagger (drf-spectacular) 적용 정리

Django 5.2 + DRF + Swagger (drf-spectacular) 적용 정리

---

1️⃣ 왜 Swagger 적용했나?

• 프론트엔드 개발자랑 백엔드 개발자가 API 스펙을 맞추기 위해
• API 요청/응답 테스트를 쉽게 하기 위해
• API 문서를 자동 생성해서 관리하기 위해

---

2️⃣ 문제 상황

문제설명

drf-yasg 사용	✅ Django 5.2 버전과 호환 안 됨 (TemplateDoesNotExist 에러)
Swagger UI 안 뜸	❌ drf-yasg/swagger-ui.html 파일을 못 찾아서 에러
호환성 문제	Django 5.x 이상에서는 drf-yasg 대신 drf-spectacular 권장

 

---

3️⃣ 해결 방법: drf-spectacular로 변경

✅ drf-spectacular 설치

pip install drf-spectacular

 

✅ settings.py 설정

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'drf_spectacular',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

 

✅ urls.py 수정

from django.contrib import admin
from django.urls import path
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('admin/', admin.site.urls),
    
    # API 스키마 JSON
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),

    # Swagger UI
    path('swagger/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

 

✅ 서버 실행

python manage.py runserver

 

✅ Swagger 접속

http://localhost:8000/swagger/

---

4️⃣ 최종 결과

기능주소

Swagger UI 문서	http://localhost:8000/swagger/
OpenAPI 스키마 JSON	http://localhost:8000/api/schema/

 

---

🔥 추가 팁

• Swagger에서는 API 요청 직접 해볼 수도 있어.
• drf-spectacular은 OpenAPI 3.0 완벽 지원.
• 프론트 개발자에게 이 URL 공유하면 → mock 서버 없이 개발 가능.

---

📚 요약

Django 5.2 + DRF + drf-spectacular 조합으로

👉 Swagger API 문서 자동 생성 성공! 🚀