API 문서에 인증 정보(API Key, Bearer Token) 포함하기

drf-spectacular를 사용하여 API 문서에 인증 방식을 명시하고, Swagger UI에서 직접 인증을 테스트할 수 있도록 설정하는 방법

인증 정보가 필요한 이유

• API 문서를 보고 엔드포인트 호출 시 401/403 에러 발생 방지

• 어떤 인증 방식을 사용하는지 명확한 안내 필요

• 인증 정보를 어디에 담아서 보내야 하는지 명시

• 인증 정보의 정확한 이름과 형식 제공

전역 설정으로 인증 방식 추가

settings.py에 SPECTACULAR_SETTINGS 설정을 통한 전역 인증 방식 정의

SPECTACULAR_SETTINGS = {
    'TITLE': 'My Project API',
    'DESCRIPTION': 'My project description',
    'VERSION': '1.0.0',
    
    'SECURITY': [
        {
            # API Key 인증 (Header)
            'APIKeyHeader': {
                'type': 'apiKey',
                'in': 'header',
                'name': 'X-Api-Key',
            },
            
            # JWT Bearer Token 인증 (Header)
            'bearerAuth': {
                'type': 'http',
                'scheme': 'bearer',
                'bearerFormat': 'JWT',
            }
        },
    ],
}

특정 View 인증 설정 변경

인증 해제

@extend_schema(
    tags=['인증'],
    summary='사용자 로그인',
    security=[],  # 전역 인증 설정 비활성화
)
def post(self, request):
    return Response(...)

특정 인증 방식만 적용

@extend_schema(
    tags=['외부 서비스 연동'],
    summary='API Key로 접근하는 외부 서비스용 API',
    security=[{'apiKeyAuth': []}],  # apiKeyAuth만 사용
)
def get(self, request):
    return Response(...)

주요 주의사항

• 문서와 실제 구현 일치: drf-spectacular 설정과 DRF의 authentication_classes 동기화

• 민감 정보 보안: 실제 API Key나 JWT를 문서에 하드코딩 금지

• 명확한 스키마 이름: userBearerAuth, serviceApiKey 등 목적이 드러나는 이름 사용

• 토큰 발급 방법 안내: API Key나 Token 발급 절차를 문서에 포함