API 문서화(Documentation)

 

API 문서

 

API 사용법을 정리한 문서

단순 구두로 설명하거나 메시지로 공유하는 방식의 한계 → API 사용법을 정리한 문서를 만드는 API 문서화(Documentation) 필요

 

조직에 맞게 완벽하게 커스터마이징 가능

별도의 학습 없이 누구나 문서 작성 및 수정 가능

코드가 변경될 때마다 문서를 따로 수정해야 함 (코드 변경 시 문서를 수정하지 않는다면, 문서와 실제 API가 달라지는 신뢰도 문제 발생)

 

 

API 문서에 담는 정보들

• Endpoint(어떤 URL에 요청해야 하는지)
• HTTP 메서드(GET, POST, PUT, DELETE...)
• 필요한 헤더(Header) 정보
• 요청 시 전송할 데이터 형식
• 응답 데이터의 구조
• 예외 상황 에러 코드 안내

API 문서는 조직에 따라 개발과 문서화에 사용하는 툴이 다르기 때문에 형식과 작성 방식이 조금씩 다름

 

주요 문서화 도구

 

Notion

IT 업계에서 널리 사용하는 협업 도구

검색, 필터, 정렬 등 편리한 기능이 많아 문서 정리에 적합함

 

Postman

API 테스트 도구로 유명

요청/응답 결과를 저장할 수 있어 API 문서화에도 자주 사용됨

API 문서를 자동 생성해 주는 기능도 지원

 

그 외 도구들

• GitBook
• Excel / Word
• Swagger UI / Redoc (OpenAPI 기반)

 

Django REST Framework + API 문서화 도구

DRF를 사용할 때는 drf-spectacular, drf-yasg를 활용해 문서 자동 생성 가능

 

Documenting your API

Documenting your API - Django REST framework

 

도구	기반	표준UI 도구 지원
drf-spectacular	OpenAPI 3.0	Swagger UI / Redoc
drf-yasg	OpenAPI 2.0	Swagger UI

 

*OpenAPI (OAS: OpenAPI Specification)

RESTful API를 설명하고 표현하기 위한 표준 스펙

API 구조를 JSON이나 YAML로 표현

사람이 읽거나 프로그램이 이해할 수 있도록 돕는 인터페이스화된 API 문서

Swagger UI나 Redoc을 통해 보기 좋은 UI로 변환 가능

 

 

DRF-Spectacular

Django REST Framework를 위한 합리적이고 유연한 OpenAPI 스키마 생성기

 

설치

pip install drf-spectacular

 

설정 추가

# settings.py
INSTALLED_APPS = [
    ...
    'drf_spectacular',
]

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

SPECTACULAR_SETTINGS = {
    'TITLE': 'MY Django API',
    'DESCRIPTION': 'Django DRF API 문서',
    'VERSION': '1.0.0',
}

 

URL 설정

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

urlpatterns = [
    ...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    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'),
]

→ /api/schema/ 자동 생성된 문서 다운로드 가능 (OpenAPI 스펙(JSON))

→ /api/schema/swagger-ui/ 자동 생성된 문서 확인 가능 (Swagger 스타일 API 문서 페이지 -더 인터랙티브함, 테스트도 가능)

→ /api/schema/redoc/ Redoc 스타일 API 문서 페이지 (더 읽기 편한 문서형 레이아웃)

/api/schema/

/api/schema/swagger-ui/

/api/schema/redoc/

 

 

커스터마이징: @extend_schema 활용

문서를 더 자세하게 설명하고 싶다면 데코레이터로 세부 설정 가능

from drf_spectacular.utils import extend_schema

class ArticleListAPIView(APIView):
    permission_classes = [IsAuthenticated]

    @extend_schema(
        tags=["Articles"],
        description="Article 목록 조회를 위한 API",
        request=ArticleSerializer,
    )
    def get(self, request):
        print("\n현재 유저의 유저네임: ", request.user.username, "\n\n")
        articles = Article.objects.all()
        serializer = ArticleSerializer(articles, many=True)
        return Response(serializer.data)

    @extend_schema(
        tags=["Articles"],
        description="Article 생성을 위한 API",
        request=ArticleSerializer,
    )
    def post(self, request):
        serializer = ArticleSerializer(data=request.data)
        if serializer.is_valid(raise_exception=True):
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)

@extend-schema

 

 

 

문서화가 코드보다 길어지는 경우도 있음 → 구조적으로 잘 분리하는 것이 중요

도구의 원리와 내부 구조를 이해하고, 내 프로젝트에 맞게 유연하게 활용해야 함