Что такое drf yasg? Узнайте все о нем здесь! 🔎📚

DRF YASG - это инструмент для генерации интерактивной документации по API на основе Django REST Framework (DRF). Он упрощает создание документации, автоматически анализируя ваши представления DRF и генерируя Swagger-спецификацию.

DRF YASG - что это?

DRF YASG (Django Rest Framework - Yet Another Swagger Generator) - это библиотека для Django Rest Framework, которая позволяет автоматически генерировать документацию к вашему API в формате Swagger.

Swagger - это набор инструментов для проектирования, построения и документирования RESTful API. Он предоставляет возможность описывать структуру и функциональность вашего API, а также генерировать интерактивную документацию, которая помогает другим разработчикам легко понимать и использовать ваше API.

Установка

Для установки DRF YASG, вам необходимо выполнить следующие шаги:

1. Установите библиотеку через pip:

pip install drf-yasg

2. Добавьте "drf_yasg" в список установленных приложений в файле settings.py вашего проекта:

INSTALLED_APPS = [
    ...
    'drf_yasg',
    ...
]

3. Включите URL-пути DRF YASG в файле urls.py вашего проекта:

from django.urls import path, include
from rest_framework import routers
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version="v1",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

router = routers.DefaultRouter()
# Регистрируйте ваши роуты здесь

urlpatterns = [
    ...
    path('api/docs/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    ...
]

После выполнения этих шагов, вы сможете получить доступ к вашей сгенерированной документации, открыв URL-путь "/api/docs/" (вы можете изменить URL-путь по своему усмотрению).

Использование DRF YASG

DRF YASG предоставляет несколько способов настройки и кастомизации документации вашего API. Ниже представлены некоторые основные возможности:

1. Автоматическая генерация документации

DRF YASG позволяет автоматически генерировать документацию на основе ваших сериализаторов, представлений и URL-путей Django Rest Framework. Для этого вам необходимо выполнить следующие шаги:

1. Создайте класс SwaggerSchemaView, который будет представлять вашу документацию:

from drf_yasg.views import get_schema_view

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version="v1",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

2. Зарегистрируйте URL-путь для вашей документации:

urlpatterns = [
    ...
    path('api/docs/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    ...
]

После выполнения этих шагов, вы сможете получить доступ к вашей сгенерированной документации, открыв URL-путь "/api/docs/" (вы можете изменить URL-путь по своему усмотрению).

2. Кастомизация документации

DRF YASG позволяет вам кастомизировать документацию вашего API, добавляя дополнительную информацию, описывая параметры запросов, устанавливая примеры запросов и ответов, и т.д. Ниже приведены некоторые методы кастомизации:

2.1. Добавление описания API

Вы можете добавить описание вашего API, указав его в классе SwaggerSchemaView:

schema_view = get_schema_view(
    openapi.Info(
        title="API Documentation",
        default_version="v1",
        description="This is the API documentation for my awesome project.",
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

Теперь описание вашего API будет отображаться на странице документации.

2.2. Добавление описания представлений

Вы также можете добавить описание к вашим представлениям. Для этого вам необходимо использовать декораторы @swagger_auto_schema или @extend_schema:

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema
from rest_framework import serializers, views, status

class MyView(views.APIView):
    @swagger_auto_schema(
        operation_summary="Summary of my view",
        operation_description="Description of my view",
        responses={
            status.HTTP_200_OK: openapi.Response(
                description="Successful response",
                schema=MySerializer(),
            )
        }
    )
    def get(self, request):
        ...

В этом примере мы добавляем описание для GET-запроса нашего представления MyView.

2.3. Добавление описания параметров запросов

Вы также можете добавлять описание и примеры для параметров запросов. Для этого вам необходимо использовать параметр manual_parameters в декораторе @swagger_auto_schema:

from django.utils.translation import gettext_lazy as _

class MyView(views.APIView):
    @swagger_auto_schema(
        ...
        manual_parameters=[
            openapi.Parameter(
                name="limit",
                in_=openapi.IN_QUERY,
                description=_("Number of results to return (default: 100)"),
                type=openapi.TYPE_INTEGER,
                required=False,
                enum=[10, 50, 100, 500, 1000],
                default=100,
            ),
        ],
    )
    def get(self, request):
        ...

В этом примере мы добавляем параметр limit с описанием и примерами в наше представление MyView.

Это лишь некоторые методы кастомизации, предоставляемые DRF YASG. Вы можете изучить документацию, чтобы узнать о других возможностях и настройках.

Заключение

DRF YASG - это мощная библиотека для автоматической генерации документации к вашему API в формате Swagger. Она позволяет вам быстро и легко создавать информативную и понятную документацию, которая облегчит работу другим разработчикам и повысит качество вашего проекта.

Использование DRF YASG - хороший способ улучшить документацию вашего API и сделать его более доступным для других разработчиков. Установите библиотеку, настройте ее и наслаждайтесь удобством работы с Swagger!