원티드 프리온보딩 인턴십 사전과제(2) - Swagger를 활용한 API 문서 자동화

<Swagger란?/>

• API 디자인, 문서 작성, API 테스트 및 클라이언트/서버 코드 생성과 같은 기능을 제공하는 프레임워크
• Swagger UI: API 문서를 대화식으로 탐색하고 시각화하는 데 사용되는 도구
• Swagger Editor: 웹 기반 편집기로써 API 디자인과 문서 작성을 도움
• Swagger codegen: API 클라이언트 및 서버 코드를 자동으로 생성해주는 도구

---

<프로젝트 소개/>

• https://github.com/lordmyshepherd-edu/wanted-pre-onboardung-backend-selection-assignment

GitHub - lordmyshepherd-edu/wanted-pre-onboardung-backend-selection-assignment: Wanted Pre-Onboarding Backend Internship Selecti

• 위 링크에서 요구하는 과제 수행 중
• 이 프로젝트는 Python 언어를 기반으로 하는 Django프로젝트이며, API 문서 자동화를 위해 Swagger를 사용하기로 함

---

<Swagger 설치 및 설정/>

- 라이브러리 설치

pip install drf-yasg

---

- settings.py 파일 설정

# 프로젝트설정폴더/settings.py

INSTALLED_APPS = [
    ...
    "drf_yasg",
    ...
]

• INSTALLED_APPS에 위에서 설치한 drf-yasg를 추가해준다

---

- urls.py 파일 설정

# 프로젝트설정폴더/urls.py
...
from django.urls import re_path
from rest_framework import permissions
from drf_yasg import openapi
from drf_yasg.views import get_schema_view
...

schema_view = get_schema_view(
    openapi.Info(	# OpenAPI 문서에 대한 기본 정보를 정의하는 객체
        title="pre-onboarding-backend API",	# API 문서 제목
        default_version="1.1.1",	# API 기본 버전
        description="원티드 프리온보딩-백엔드 과정 사전 과제입니다.",	# API 간략 설명
        contact=openapi.Contact(email="ehdro418@naver.com"),	# API 문서 담당자 연락처
        license=openapi.License(name="mit"),	# API에 적용되는 라이선스
    ),
    public=True,	# 문서 공개 여부
    permission_classes=[permissions.AllowAny],	# 문서 접근 권한
)

urlpatterns = [
    re_path(
        r"swagger(?P<format>\.json|\.yaml)",	# swagger로 시작하는 URL에 대해 처리, ".json", ".yaml" 형식을 선택적으로 받음
        schema_view.without_ui(cache_timeout=0), # OpenAPI 문서를 JSON 또는 YAML 형식으로 반환, 캐싱 사용하지 않음
        name="schema-json",
    ),
    path(
        r"swagger",	# swagger로 시작하는 URL에 대해 처리
        schema_view.with_ui("swagger", cache_timeout=0), # Swagger UI 제공, 사용자는 웹 브라우저를 통해 API 문서를 참조하고 테스트 할 수 있음
        name="schema-swagger-ui",
    ),
    path(
        r"redoc", schema_view.with_ui("redoc", cache_timeout=0), name="schema-redoc-v1"
    ),	# redoc으로 시작하는 URL에 대해 처리, ReDoc 뷰어를 사용해서 API 문서 시각화
    ...
    (기존 path들)
]

---

- 데코레이터 설정

• users 앱 데코레이터
• articles 앱 데코레이터
• tags: Swagger UI 문서의 섹션 또는 카테고리를 나타냄
• manual_parameters: 메서드에 필요한 매개변수를 명시하는 데 사용되며, openapi.Parameter 객체의 목록을 받아들임
• request_body: API 호출 시 클라이언트로부터 받아올 요청 바디의 스키마 표현을 정의함
• responses: API 호출에 대한 응답 코드와 설명을 정의함
• openapi.Parameter 객체 옵션 설명
  • "article_id": 매개변수의 이름
  • IN_PATH: 매개변수가 URL 경로에 위치하도록 지정
  • description: 매개변수에 대한 간단한 설명
  • required: True이면 해당 매개변수가 필수로 지정되어야 함, False이면 필수는 아님
  • type: 매개변수의 데이터 타입

:sparkles:Feat: 스웨거 데코레이터 추가 · goodminjeong/wanted-pre-onboarding-backend@fc3c50a

:sparkles:Feat: 스웨거 데코레이터 추가 · goodminjeong/wanted-pre-onboarding-backend@fc3c50a

http://127.0.0.1:8000/swagger

http://127.0.0.1:8000/redoc