Оглавление

Базовая настройка документации

Установка пакетов

Есть два самых популярных приложения для оформления документации: drf-yasg и drf-spectacular. Оба поддерживают Swagger и ReDoc, однако drf-spectacular более новый и поддерживает формат OpenAPI 3.0, поэтому в нашем курсе рассматриваем его. Устанавливается он как обычный python-пакет.


                    
poetry add drf-spectacular

После установки нужно добавить приложение в INSTALLED_APPS в файл settings.py и настроить константу DEFAULT_SCHEMA_CLASS, как показано ниже:


                    
# settings.py 

INSTALLED_APPS = [
    # YOUR APPS
    'drf_spectacular',
]


# YOUR SETTINGS



REST_FRAMEWORK = {
    # OTHER REST FRAMEWORK SETTINGS 
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

Больше ничего делать не Нужно. Но, если хочется, можно еще переопределить базовые заголовки нашей документации.


                    
# settings.py

SPECTACULAR_SETTINGS = {
    'TITLE': 'Hunting API',
    'DESCRIPTION': 'Awesome hunting project',
    'VERSION': '1.0.0',
}

Настройка URL

Для того чтобы настроить URL документации, нужно прописать не один, а два URL:

Первый (в нашем примере ’api/schema/’) — URL, по которому будет отдаваться схема OpenAPI.

Второй (в нашем примере ‘api/schema/swagger-ui/’) — URL, по которому будет отдаваться сама документация.

Обратите также внимание на параметр url_name='schema' в вызове SpectacularSwaggerView.as_view. Он должен совпадать с именем URL схемы OpenAPI.


                    
# urls.py

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView


urlpatterns = [
		# YOUR ROUTES HERE

    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/swagger-ui/', 
					SpectacularSwaggerView.as_view(url_name='schema'), 
					name='swagger-ui'),
]

Кастомизация View

Для переопределения чего-то в сгенерированной по методу View документации используется декоратор `@extend_schema`. Он умеет переопределять практически всё. Из самого важного:

request определяет Serializer для входящих данных (если автоматически определился не тот, что нужен).

responses определяет список возможных Serializer для ответа.

description определяет описание метода в документации.

summary определяет короткое описание метода.

deprecated отмечает, что метод устарел и будет удалён в ближайшее время.

Пример использования:


                    
# views.py 

class VacancyListView(ListAPIView):
    queryset = Vacancy.objects.all()
    serializer_class = VacancySerializer

    @extend_schema(
        description="Retrieve vacancy list",
        summary="Vacancy list"
    )
    def get(self, request, *args, **kwargs):
        # Method code here

Кастомизация ViewSet

Для ViewSet используется отдельный декоратор @extend_schema_view, т. к. обычно мы обычно не пишем методы во ViewSet.

В этом декораторе объявлены атрибуты по названиям методов, которые есть у ViewSet. Для переопределения документации в атрибут с соответствующим названием метода необходимо передать результат вызова @extend_schema. Например, ниже мы переопределяем документацию для метода list:


                    
# views.py

@extend_schema_view(
    list=extend_schema(description="Retrieve skills", summary="Skills list"),
)
class SkillViewSet(ModelViewSet):
    queryset = Skill.objects.all()
    serializer_class = SkillSerializer