Swagger no Django REST

A sua API Django REST funciona, mas não tem documentação. Cada novo desenvolvedor precisa ler o código-fonte para entender os endpoints. O drf-yasg gera documentação Swagger e ReDoc interativa automaticamente a partir das suas views e serializers.

TL;DR: Adicione documentação interativa Swagger e ReDoc a uma API Django REST Framework usando drf-yasg.
Stack: Python, Django, Django REST Framework, drf-yasg, Swagger
Nível: Iniciante
Tempo de leitura: ~5 min

Instalar drf-yasg

pip install drf-yasg

Registrar no settings.py

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

Configurar Swagger no urls.py

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="API",
        default_version='v1',
        description="Descrição da API",
        contact=openapi.Contact(email="voce@exemplo.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    ...
    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'),
    ...
]

Agrupar endpoints por tag

from rest_framework.views import APIView
from drf_yasg.utils import swagger_auto_schema

class MinhaView(APIView):
    @swagger_auto_schema(tags=['Minha Categoria'])
    def get(self, request):
        # seu código aqui

Definir schema do corpo da requisição

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema

post_schema = openapi.Schema(
    type=openapi.TYPE_OBJECT,
    properties={
        'internationalTitle': openapi.Schema(type=openapi.TYPE_STRING, description='Título internacional'),
        'year': openapi.Schema(type=openapi.TYPE_INTEGER, description='Ano de lançamento'),
        'genre': openapi.Schema(type=openapi.TYPE_STRING, description='Gênero'),
    },
    required=['internationalTitle', 'year']
)

class CreateRecommendationView(APIView):
    @swagger_auto_schema(request_body=post_schema)
    def post(self, request):
        ...

O que você construiu

Documentação Swagger e ReDoc gerada automaticamente a partir das suas views Django REST Framework, acessível em /swagger/ e /redoc/. O decorator @swagger_auto_schema permite anotar views com tags, schemas de corpo de requisição e tipos de resposta.

Próximos passos

• Proteja o endpoint Swagger com autenticação em produção. Expor o schema completo da sua API publicamente é um risco de segurança.
• Use swagger_auto_schema nas views baseadas em serializers para inferência automática de schema.
• Exporte o schema como arquivo JSON estático para Postman ou outros clientes de API: /swagger.json.

Dúvidas ou feedback? Me encontre no LinkedIn ou GitHub.