[DRF] drf_yasg로 API 문서화 & GitHub Repository에 Commit하기

DRF 기반으로 게시판 서비스를 만들어보자❗ 마무리

📑 drf_yasg로 API 문서화

개발자들에게는 API라는 결과물에 대한 API 문서가 필요하다.

이때 일일이 작성하지 않아도 되도록 API 문서화를 자동으로 도와주는 drf_yasg라는 도구를 활용할 수 있다.

API의 각 endpoint별로 주소, 요청 메소드, 입력해야 하는 데이터와 각 데이터별 타입, 응답 양식까지 한 번에 정리해둔 문서를 생성할 수 있다.

📍 drf_yasg 패키지 적용하기

우선 패키지를 설치한다.

$ pip install drf-yasg

settings.py의 INSTALLED_APPS에 drf_yasg를 등록한다.

다음으로 프로젝트의 urls.py에서 문서에 대한 url을 설정한다.
공통적인 부분이므로 복사해서 작성하면 된다.

공식 문서
https://drf-yasg.readthedocs.io/en/stable/readme.html#configuration

...
from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

...

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

urlpatterns += [
   path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]

runserver 해보니 에러메시지가 생겼다.

ModuleNotFoundError: No module named 'pkg_resources' 

pkg_resources 모듈을 찾을 수 없다고 한다.
이 모듈은 일반적으로 setuptools 패키지에 포함되어 있다고 하니 설치해주자.

$ pip install setuptools

다시 서버를 시작해보니 에러메시지는 사라졌다.

📍 실행

http://127.0.0.1:8000/swagger/ 로 들어가보면 이런 화면이 나온다.
각 요청별 내용과 모델별 설명을 볼 수 있다.

http://127.0.0.1:8000/redoc/ 에 들어가보면 다른 디자인의 문서를 확인할 수 있다.

📍 필드에 설명 추가하기

필드마다 수동적으로 설명을 붙이려면 시리얼라이저에 help_text를 활용해서 설명을 추가하면 된다.

help_text는 API 문서화 도구(drf-yasg, Swagger 등)에서 각 필드에 대한 설명이나 안내 메시지를 제공하는 데 사용된다.

class RegisterSerializer(serializers.ModelSerializer):
    email = serializers.EmailField(
        help_text="이메일(Unique)",
        required=True,
        validators=[UniqueValidator(queryset=User.objects.all())],
    )
    password = serializers.CharField(
        help_text="비밀번호",
        write_only=True,
        required=True,
        validators=[validate_password],
    )
    password2 = serializers.CharField(
        help_text="비밀번호 재입력", write_only=True, required=True)

이런 식으로 시리얼라이저에서 사용할 수 있다.
다시 실행해 보면 설명이 잘 적용되어 있다.

📑 깃허브 레포지토리에 올리기

$ git init
$ git add .
$ git commit -m "Commit message"

나의 경우에는 git add .를 하자

warning: LF will be replaced by CRLF

라는 에러메시지가 엄청 길게 나타났다.

찾아보니 LF는 Unix/Linux 계열에서 사용하는 줄바꿈 문자이고, CRLF는 Windows에서 사용하는 줄바꿈 문자로, git이 os마다 다른 형식을 어떻게 받아들여야 할지 모르기 때문에 발생하는 경고라고 한다.

git에 코드를 커밋할 때 LF와 CRLF를 서로 변환해주는
git config --global core.autocrlf true
명령어로 간단히 해결되었다.

깃허브에서 레포지토리를 생성하고 마무리한다.

$ git remote add origin https://github.com/어쩌구.git
$ git push origin master