콘텐츠로 이동

API 문서 (상)#

2024 iThome 철인 대회

이 글은 Django Ninja 시리즈 튜토리얼의 17번째 글이에요. 제4장——API 문서를 시작할게요.

「코드에 따라 자동으로 API 문서 생성하기」는 Django Ninja의 큰 장점이에요.

사실 API 문서의 자동화는 제가 실무 프로젝트에서 Django REST framework 대신 Django Ninja로 전환하게 된 가장 큰 이유이자, Django Ninja를 배우기 시작한 계기였어요.

Django Ninja는 API 문서를 수동으로 작성 (우리는 API Blueprint를 사용했어요) 하는 시간을 많이 줄여줘요. 특히 API 사양이 변경될 때 문서를 동기화해서 수정할 필요가 없어서 문서 유지 관리에 드는 노력을 크게 덜어주죠.

이 기능이 얼마나 중요한지 알 수 있겠죠.

튜토리얼 순서에 대한 고려#

그렇다면 왜 시리즈의 17번째 글인 이 글에 와서야 Django Ninja의 API 문서 기능을 소개하기 시작했을까요?

훌륭한 API 문서를 생성하려면 Schema 사용에 대한 어느 정도의 이해가 필요하기 때문이에요. 그래서 어쩔 수 없이 제3장 이후로 배치하게 되었어요.

이제 Django Ninja를 사용하여 고품질의 API 문서를 생성하는 방법을 알아볼게요.

이 글의 모든 코드 변경 사항은 이 PR을 참고해 주세요.

GitHub 예제 프로젝트#

👉 Django-Ninja-Tutorial

Documentation as Code#

현대 소프트웨어 개발에서 「Documentation as Code」 (DoC)는 점차 인정받고 있는 개념이에요.

DoC는 문서와 코드를 긴밀하게 결합하는 것을 의미하며, 개발자는 「소프트웨어 코드 개발과 동일한 프로세스 및 도구」를 사용하여 문서를 작성하고 유지 관리해요.

문서는 코드 변경에 따라 자동으로 업데이트되며, 두 가지는 항상 일관성을 유지하게 되죠.

이는 개발 효율성을 높일 뿐만 아니라 문서가 오래되어 발생하는 원활하지 않은 의사소통이나 오해를 줄여줘요.

Django Ninja의 자동 문서 생성 기능은 의심할 여지 없이 「Documentation as Code」 정신의 실천이에요.

API 라우팅, 뷰 함수, Schema 등의 코드를 작성함으로써 OpenAPI 표준을 충족하는 문서를 자동으로 생성할 수 있고, 코드가 변경될 때 이러한 문서들도 자동으로 변경 결과를 반영하므로 수동으로 유지 관리할 필요가 없어요.

Django Ninja 자동화 API 문서의 두 가지 핵심#

Django Ninja에서 고품질의 API 문서를 생성하려면 주로 두 가지 핵심이 관련돼요:

  1. Django Ninja 설정: Django Ninja에는 API 문서의 세부 사항을 제어하는 설정이 내장되어 있으며, 이것이 이 글의 핵심이에요.
  2. Pydantic 설정: 이것은 다음 글에서 다룰 내용으로, Schema를 효과적으로 정의하여 다양한 세부 사항이 API 문서에 자동으로 나타나도록 하는 방법을 설명해요.

여기까지 보니 조금 기대되지 않나요? ☺️

프로젝트 API 문서 현황#

문서 품질을 대대적으로 개선하기 전에, 현재 API 문서가 얼마나 「기본적」인지 먼저 살펴볼게요.

Django 서버를 시작한 후, 다음 URL을 방문하면 현재 API의 문서를 확인할 수 있어요:

http://127.0.0.1:8000/docs

현재 문서 내용은 다음과 같아요:

「개발자에게 유용하고 읽기 쉬운지」의 관점에서 간단히 분석해 볼게요.

문제 분석#

첫째로, 그룹화가 되어 있지 않아요!

Django user app과 post app의 API가 모두 섞여 있어서, API가 점점 많아지면 매우 복잡해 보일 거예요. 이것이 가장 먼저 해결해야 할 문제예요.

둘째로, 「Get Users」, 「Create Post」와 같은 API 설명은 명백히 뷰 함수 이름에서 자동으로 변환된 거예요. 정보가 제한적이고 충분히 구어체적이지 않으며 상세하지 않아서, 간단히 말해 「독자 친화적」이지 않아요.

유일한 POST API를 클릭해서 내용을 살펴볼게요:

내부 설명에 「게시글 추가」가 있는데, 이것은 사실 뷰 함수의 docstring에서 가져온 거예요:

@router.post(path='/posts/')
def create_post(...) -> tuple[int, dict]:
    """
    게시글 추가
    """
    ...

HTTP 요청 body의 예시도 다시 볼게요:

{
    "title": "string",
    "content": "string",
    "user_id": 0
}

이상적이지 않다고 할 수밖에 없네요. "string"과 같은 예시는 「타입(Type)」만 보여줄 뿐, 실제 세상의 게시글 제목이나 내용을 시뮬레이션하지 못해요.

위의 문제들이 바로 우리가 API 문서를 개선해야 할 핵심이에요.

그 중 요청 body 예시는 Schema 설정과 관련이 있으며, 다음 글의 중심 내용이에요.

이 글에서는 먼저 Django Ninja 설정에 초점을 맞추어 하나씩 소개해 드릴게요.

1. Tags를 사용하여 API 그룹화하기#

우리가 첫 번째로 해결해야 할 것은 API의 그룹화(분류) 문제예요.

문서 구조를 더 명확하게 만들기 위해 Django Ninja는 Tags를 사용하여 API를 그룹화하는 것을 지원해요. 문서를 구성하는 데 도움이 될 뿐만 아니라, 개발자나 사용자가 필요한 API를 더 빨리 찾을 수 있게 해줘요.

Tags 그룹화는 두 곳에서 설정할 수 있어요.

1차 라우팅 그룹화#

가장 일반적인 방법은 1차 라우팅(루트 라우터)에서 설정하는 거예요:

# NinjaForum/api.py
api.add_router(prefix='', router='user.api.router', tags=['User'])
api.add_router(prefix='', router='post.api.router', tags=['Post'])

동일한 Django app의 API는 일반적으로 동일한 그룹에 속하기 때문이에요.

라우팅 데코레이터 그룹화#

라우팅 데코레이터에서 그룹화를 설정할 수도 있지만, 이는 상대적으로 「예외적인」 상황에 속하며 주로 다음에 사용된다고 생각해요:

  1. 전체 프로젝트에 Django app이 단 하나뿐일 때.
  2. 동일한 Django app에서 다른 그룹화가 필요할 때.

예를 들어 아래 예시에서는 Django app을 구분하지 않지만 여전히 그룹화 요구 사항이 있어요:

from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/users/", tags=["User"])
def get_users(request):
    ...

@api.post("/posts/", tags=["Post"])
def create_post(request, title: str):
    ...

대부분의 경우 1차 라우팅에서 그룹화를 진행하는 것을 추천해요.

그렇지 않으면 위의 예시처럼 하나하나 표시해야 해서 실천하기에 조금 번거롭거든요.

2. 라우팅 데코레이터의 문서 설정#

Django Ninja의 라우팅 데코레이터는 기본적인 API 경로를 설정할 수 있을 뿐만 아니라 API의 설명 텍스트를 추가할 수 있게 해주며, 이러한 내용은 생성된 API 문서에 직접 반영돼요.

이러한 설정을 통해 API의 매개변수, 응답, 심지어 의도에 대한 설명을 추가하여 문서를 더 포괄적으로 만들 수 있어요.

description과 summary 매개변수를 통해 각 API 라우팅에 설명을 제공할 수 있어요. 그러나 description은 위에서 언급한 「docstring을 API 설명으로 변환」하는 효과를 대체하므로, 저는 평소에 summary만 작성해요.

어쨌든 우리는 Python을 작성하니까, docstring은 필수죠!

코드는 다음과 같아요:

@router.get(..., summary='게시글 목록 가져오기')
def get_posts(...) -> QuerySet[Post]:
    """
    게시글 목록 가져오기
    """
    ...

지금까지의 실제 개선 효과(그룹화, API 설명):

아주 좋네요!

3. NinjaAPI 설정#

NinjaAPI 클래스의 초기화 설정을 통해 몇 가지 전역 API 문서 세부 사항을 사용자 정의할 수 있어요. 예를 들면:

# NinjaForum/api.py
from ninja import NinjaAPI

api = NinjaAPI(
    title="Ninja Forum API",
    version="1.0",
    description="이것은 독자가 참고할 수 있는 Ninja Forum의 API 문서입니다."
)

이에 해당하는 실제 효과:

NinjaAPI의 초기화 설정은 매우 다양해요——필요한 설정이 있을 수 있어요.

여기는 간단한 예시일 뿐이며, 더 많은 설정 세부 사항은 문서를 확인해 주세요.

소결#

이 글에서는 Django Ninja가 자동으로 API 문서를 생성하는 일반적인 설정을 탐구하여 「Documentation as Code」 정신을 실현할 수 있게 했어요——코드와 문서를 쉽게 일치하게 유지하고, 수동으로 유지 관리하는 번거로움을 줄일 수 있죠.

그러나 API 문서의 품질은 우리가 Schema의 세부 사항을 어떻게 정의하느냐에 달려 있어요.

다음에는 이 주제에 대해 깊이 있게 탐구하고, Pydantic의 Field 매개변수 설정을 통해 고품질의 문서 예시를 제공하여 API 문서의 가독성과 명확성을 한층 더 향상시키는 방법을 설명할게요.