DRF와 API 문서 자동화, drf-spectacular
DRF(Django REST Framework)란?
Django만으로 API 서버를 개발할 수도 있지만 Django에 DRF 패키지를 추가로 설치하면 REST API 서버를 좀 더 쉽게 개발할 수 있다.
API 문서는?
API 사용법을 알려주는 문서를 말한다. 아래 YouTube DATA API 문서가 그 예다. API 문서를 프런트 개발자한테 공유해야 프런트 개발자가 웹페이지를 개발할 수 있다.
API 문서 자동화가 필요한 이유는?
API 문서를 일일이 PDF로 작성하든 위키로 작성하든 굉장히 시간이 많이 걸린다. 또 코드는 변경했지만 문서 변경은 깜빡하는 경우가 많아서 API 문서가 현재 API 서버 작동과 다른 경우도 많이 발생한다. API 문서 자동화툴을 사용하면 코드 변경 시 API 문서에 자동 반영되어 개발자의 시간과 수고를 절약할 수 있다. SpringBoot, NestJs, Django(DRF) 등 각 프레임워크마다 API 문서 자동화 라이브러리가 있다.
drf-spectacular
drf-spectacular는 API 문서 자동화 팩키지 중 하나로 DRF로 API 서버를 개발할 때 API 문서를 OpenAPI 3 기반으로 생성해준다. 코드와 통합된 한 저장소에서 API 문서를 관리할 수 있고, 코드 변경 시 예를 들면 시리얼라이저 변경 시 자동으로 문서에 반영되어서 좋다.
drf-spectacular 설정 방법
settings.py에 아래 내용을 추가한다.
INSTALLED_APPS += [
"drf_spectacular",
]
REST_FRAMEWORK = {
...
"DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}
SPECTACULAR_SETTINGS = {
"TITLE": "Form API",
"DESCRIPTION": "Form API Documentation",
"VERSION": "1.0.0",
"SWAGGER_UI_SETTINGS": {
"docExpansion": "list",
"defaultModelRendering": "example",
"defaultModelExpandDepth": 10,
"defaultModelsExpandDepth": 10,
"deepLinking": True,
"displayRequestDuration": True,
"persistAuthorization": True,
"syntaxHighlight.activate": True,
},
}
urls.py에 아래 내용을 추가한다.
from drf_spectacular.views import SpectacularSwaggerView, SpectacularJSONAPIView, SpectacularRedocView
urlpatterns = [
...
path("openapi.json/", SpectacularJSONAPIView.as_view(), name="schema"),
path("swagger-ui/", SpectacularSwaggerView.as_view(), name="swagger-ui"),
path("redoc/", SpectacularRedocView.as_view(), name="redoc"),
]
그 뒤 API 서버를 실행해서 /swagger-ui/에 접속하면 아래 예와 같은 화면을 볼 수 있다.
/redoc에 접속하면 redoc 문서를 볼 수 있다.
