[Swagger] drf-spectacular로 REST API 문서 자동 생성

최근 팀프로젝트에서 스웨거를 자주 사용하고 있습니다. 기본 사용법 익혔지만 개념적으로 한번 더 정리해보면 좋을 것 같아 포스팅으로 남겨봅니다.

 

 

 

 

 

Swagger

: Open Api Specification(OAS)를 위한 프레임워크

 

Swagger는 API 스펙에 대한 명세를 확인할 수 있는 공유 문서로, 백엔드에서 구현한 REST API를 프론트엔드에서 쉽게 확인할 수 있게 도와줍니다. 이를 통해 개발자들은 API의 사용법과 엔드포인트, 요청 및 응답 형식을 직관적으로 이해할 수 있으며, 문서화된 내용을 바탕으로 프론트엔드와 백엔드 간의 원활한 협업이 가능해집니다.

코드 기반으로 API문서가 자동으로 생성되고 코드가 변경되면 문서도 자동으로 업데이트도 됩니다.

 

OAS(OpenAPI Specification)는 는 무엇일까?

 

RESTful 웹서비스를 약속된 규칙에 따라 API 스펙을 JSON과 YAML 형식으로 표현합니다.

이런 형식은 다양한 언어로 프로그램이 개발되었더라도 직접 소스코드를 보거나 추가 문서 필요 없으니 서비스를 직관적으로 이해할 수 있습니다.

 

 

API는 왜 중요할까?

 

개발 및 관리의 효율성 

API를 사용하면, 개발자들은 이미 만들어진 기능을 블록처럼 가져다 쓸 수 있습니다. 매번 새로운 개발을 할 필요가 없어 개발 시간이 단축, 비용 절감이 되고 Swagger같은 API 문서만 있으면 누구나 쉽게 이해할 수 있어서 협업과 유지보수가 수월해집니다.

 

유연성 및 확장성

API를 사용하면 서비스의 신규 개발이나 웹/앱 채널 확장성이 좋고 특히 타사 서비스와의 연계가 용이합니다.

예를 들어 내 애플리케이션에 지도 기능을 추가하고 싶다면, 처음부터 직접 개발하기보다는 구글이나 네이버의 지도 API를 이용하는 것이 상당한 시간절약이 되는 것 처럼.

 

 

간단한 실습을 통해서 사용법을 더 익혀봅시다.

 

drf-spectacular는 앞서 설명한 OAS 3.0버전에 맞게 문서화를 도와주는 라이브러리입니다.

drf-yasg 패키지도 같은 기능이지만 OAS 2버전으로 최근엔 사용하지 않는다고 합니다.

 

1. 장고 프로젝트에서 drf-spectacular 패키지를 설치합니다.

pip install drf-spectacular

 

 

2. 패키지를 사용하기 위해 settings.py에 아래 세팅값을 정의해줍니다.

# settings.py

INSTALLED_APPS = [
    ...
    'drf_spectacular',   # installed_app에 추가
    ...
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    "TITLE": "API 명세 이름",
    "DESCRIPTION": "상세설명",
    "VERSION": "0.0.1",
    "SERVE_INCLUDE_SCHEMA": False,
    "CONTACT": {
        "name": "contact name",
        "url": "contact.me",
    },
}

 

SPECTACULAR_SETTINGS는 실제로 swagger화면에 옵션을 추가하는 정의인데 자세한 설정값은 아래 문서에서 확인가능합니다.

https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

 

 

 

3. 마지막으로 url.py 에 패턴을 등록하면 스웨거 화면을 띄울 수 있습니다.

예전 자료를 보면 json, yaml과 관련된 path 정의가 필요했지만 최신 버전에서는 SpectacularAPIView만 정의해주면 됩니다.

# 이전 방식
from drf_spectacular.views import SpectacularJSONAPIView
from drf_spectacular.views import SpectacularYAMLAPIView

urlpatterns = [ 
    path("docs/json/", SpectacularJSONAPIView.as_view(), name="schema-json"),
    path("docs/yaml/", SpectacularYAMLAPIView.as_view(), name="swagger-yaml"),
    ...
    ]
    
# 최신 방식 
from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView

urlpatterns = [
    # YOUR PATTERNS
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI:
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),

출처: https://devspoon.tistory.com/256 [devspoon 오픈소스 개발자 번뇌 일지:티스토리]

 

 

 

@extend_schema는 drf-spectacular 패키지에서 제공하는 데코레이터로, Django REST Framework (DRF) 뷰 또는 뷰셋에 OpenAPI 스키마에 대한 추가적인 정보를 제공하는 데 사용됩니다.

이 데코레이터를 사용하면 API 문서에 대한 더 구체적이고 사용자 정의된 설명, 요청 및 응답 형식, 상태 코드 등을 추가할 수 있습니다.

아래 링크 참고

https://drf-spectacular.readthedocs.io/en/latest/customization.html

 

 

 

마무리

Swagger는 실무에서도 정말 중요한 툴이다 보니 이번 포스팅으로 개념을 다시 정리하면서 익힐 수 있었습니다.😎👍