Swagger란?

250121

Swagger란?

Swagger(OpenAPI Specification)는 RESTful API를 설계, 문서화, 테스트하기 위한 오픈소스 프레임워크이다. API의 엔드포인트, 요청/응답 형식, 인증 방식 등을 표준화된 방식으로 정의할 수 있게 해 주며, 개발자들이 쉽게 API를 이해하고 사용할 수 있도록 도와주는 역할을 한다.

 

Swagger의 장점

1. 자동화된 문서화

• API 명세가 코드와 함께 자동으로 업데이트되어 항상 최신 상태를 유지.
• 개발자가 별도로 문서를 작성하고 관리할 필요가 없어 시간과 노력이 절약.
• 문서화 누락이나 불일치 문제를 방지할 수 있음.

2. 상호작용 가능한 문서

• Swagger UI를 통해 API를 직접 테스트해 볼 수 있음.
• 실제 요청과 응답을 확인할 수 있어 각 API에 대한 이해도가 높아짐. → 협업 효율 향상

3. 코드 생성

• API 명세를 바탕으로 다양한 언어의 클라이언트 SDK를 자동으로 생성 가능.
• 서버 스텁 코드도 자동 생성이 가능하여 개발 시간을 단축할 수 있음.

4. 표준화

• API 설계와 문서화에 대한 업계 표준을 따르므로 일관성이 유지.
• 팀원 간 협업을 용이하게 하고 새로운 팀원의 온보딩 과정 이해를 돕는다.

Swagger의 단점

1. 성능 영향

• 자동 문서화를 위한 어노테이션과 설정이 많아질수록 애플리케이션의 실행 속도가 영향을 받을 수 있다.
  →  프로덕션 환경에서는 Swagger UI를 비활성화 권고.

2. 보안 위험

• Swagger UI가 공개되어 있으면 API의 상세 정보가 노출될 수 있다.
• 프로덕션 환경에서는 접근 제한이 필요.

3. 유지보수 부담

• 상세한 API 문서화를 위해서는 많은 어노테이션과 설정이 필요.
• 과도한 문서화는 코드의 가독성을 해칠 수 있다.

4. 학습 곡선

• OpenAPI Specification의 문법과 구조를 이해.
• 프레임워크별 설정 방법과 어노테이션 사용법을 학습해야함.

 

 

예시

#urls.py
from django.contrib import admin
from django.urls import path, include
from rest_framework import permissions
from rest_framework import routers
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="TEST API",
        default_version="v1",
        description="API documentation",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="contact@testapi.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

router = routers.DefaultRouter()

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/v1/accounts/", include("accounts.urls")),
    path(
        "swagger/", schema_view.with_ui("swagger", cache_timeout=0), name="swagger-ui"
    ),
]

 

#views.py
from django.contrib.auth import authenticate
from rest_framework import status
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework_simplejwt.tokens import RefreshToken
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
from .serializers import UserSerializer,LoginSerializer
from .models import Role


#회원가입
class SignupAPIView(APIView):
    @swagger_auto_schema(
            request_body=UserSerializer,
            responses={201: openapi.Response('Signup successful', UserSerializer)}
        )
    def post(self, request):
        serializer = UserSerializer(data=request.data)
        if serializer.is_valid():
            user = serializer.save()
            role_data = request.data.get("roles")

            if role_data:
                for role in role_data:
                    role_instance = Role.objects.get_or_create(
                        user=user, role=role["role"]
                    )[0]
                    role_instance.save()
            else:
                Role.objects.create(user=user, role="USER")

            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)