Swagger документация с drf-spectacular

drf-spectacular генерирует OpenAPI 3.0 схему и Swagger UI для DRF.

Установка

pip install drf-spectacular

INSTALLED_APPS = [
    ...
    'drf_spectacular',
]

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

Настройка схемы

SPECTACULAR_SETTINGS = {
    'TITLE': 'Task Manager API',
    'DESCRIPTION': 'API для управления задачами',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

URLs

from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

Открой /api/docs/ для интерактивной документации.

Аннотации

from drf_spectacular.utils import extend_schema, OpenApiParameter

class TaskViewSet(viewsets.ModelViewSet):

    @extend_schema(
        summary='Список задач',
        description='Возвращает задачи текущего пользователя',
        parameters=[
            OpenApiParameter('status', str, description='Фильтр по статусу'),
        ],
    )
    def list(self, request):
        return super().list(request)

    @extend_schema(summary='Создать задачу')
    def create(self, request):
        return super().create(request)

Документирование сериализатора

class TaskSerializer(serializers.ModelSerializer):
    class Meta:
        model = Task
        fields = ['id', 'title', 'status']
        # drf-spectacular автоматически генерирует описание из модели

Генерация схемы в файл

python manage.py spectacular --color --file schema.yml