Introducción
Siempre he opinado que sin importar para que empresa o cliente desarrolle, todos mis proyectos deben ser de tal forma escalable, modulares y de código limpio, que si por algún motivo dejo de ser yo el desarrollador de mi cliente el próximo programador que tome mi proyecto debe poder comprender perfectamente el código y así escalarlo o mejorarlo de ser requerido.
Lo mismo pasa con nuestras API, el que tenga una buena documentación es esencial para poder realizar cualquier modificación, mejora o simplemente comprender como funciona para que comprendan cómo consumir los endpoints.
En el ecosistema Django REST Framework (DRF), drf-spectacular es hoy la librería más recomendada para generar documentación automática OpenAPI 3.0/3.1, desplazando a drf-yasg, que ha quedado desactualizado.
En este artículo te enseño cómo integrar drf-spectacular y drf-spectacular[sidecar] paso a paso para que puedas documentar tu API con Swagger UI y Redoc, de forma moderna, limpia y profesional.
Instalación
pip install drf-spectacular
pip install drf-spectacular-sidecar
El paquete [sidecar] incluye los archivos estáticos necesarios para servir
Swagger UI y ReDoc sin configuraciones externas.
Configuración en settings.py
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
Ahora Registra las aplicaciones instaladas en el settings.py hazlo asi para mantener un codigo limpio, bien estructurado y con buenas practicas:
Ventajas de esta práctica:
– Claridad: Sabes inmediatamente qué tipo de aplicación es cada una
– Mantenibilidad: Es más fácil agregar/quitar aplicaciones en la categoría correcta
– Organización: Especialmente útil en proyectos grandes con muchas dependencias
– Colaboración: Otros desarrolladores entienden rápidamente la estructura
– Debugging: Si hay problemas con una app de terceros, sabes exactamente dónde buscar
DJANGO_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
]
PROJECT_APPS = [
'apps.user',
]
THIRD_PARTY_APPS = [
'rest_framework',
'drf_spectacular',
'drf_spectacular_sidecar',
]
INSTALLED_APPS = DJANGO_APPS + PROJECT_APPS + THIRD_PARTY_APPS
Esto permite que cada ViewSet, APIView o GenericViewSet
genere automáticamente su documentación a partir de serializers, parámetros y métodos definidos.
Crear las rutas para la documentación
Edita tu archivo urls.py principal (por ejemplo, config/urls.py) y añade lo siguiente:
from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView, SpectacularRedocView
urlpatterns = [
path('admin/', admin.site.urls),
# Endpoints de la API
path('api/', include('apps.posts.api.router')),
# Esquema OpenAPI
path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
# Swagger UI
path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
# ReDoc UI
path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]
Ahora tenemos disponibles:
/api/schema/→ Archivo OpenAPI JSON/api/docs/→ Interfaz Swagger UI/api/redoc/→ Interfaz ReDoc
Ejemplo con un ModelViewSet
Supongamos que tienes una aplicación posts con el modelo Post:
from rest_framework import viewsets
from apps.posts.models import Post
from apps.posts.api.serializers import PostSerializer
class PostViewSet(viewsets.ModelViewSet):
queryset = Post.objects.all()
serializer_class = PostSerializer
Y el router correspondiente:
from rest_framework.routers import DefaultRouter
from apps.posts.api.viewsets import PostViewSet
router = DefaultRouter()
router.register(r'posts', PostViewSet, basename='posts')
urlpatterns = router.urls
Con esto, drf-spectacular nos genera automáticamente la documentación de los endpoints CRUD:
GET /api/posts/
POST /api/posts/
GET /api/posts/{id}/
PUT /api/posts/{id}/
DELETE /api/posts/{id}/
Personalizar información general del esquema
Puedes definir metadatos globales en tu archivo settings.py:
SPECTACULAR_SETTINGS = {
'TITLE': 'API del Proyecto Django',
'DESCRIPTION': 'Documentación de la API para la gestión de posts.',
'VERSION': '1.0.0',
'SERVE_INCLUDE_SCHEMA': False,
'LICENSE': {'name': 'MIT License'},
'CONTACT': {
'name': 'Jorge Romero Contreras',
'email': '[email protected]',
},
}
Ejemplo avanzado: acciones personalizadas
Puedes documentar también endpoints personalizados dentro de un ViewSet usando el decorador
@extend_schema de drf-spectacular:
from rest_framework.decorators import action
from rest_framework.response import Response
from drf_spectacular.utils import extend_schema
class PostViewSet(viewsets.ModelViewSet):
queryset = Post.objects.all()
serializer_class = PostSerializer
@extend_schema(description="Obtiene los posts publicados recientemente")
@action(detail=False, methods=['get'])
def recent(self, request):
posts = Post.objects.order_by('-created_at')[:5]
serializer = self.get_serializer(posts, many=True)
return Response(serializer.data)
Esto generará automáticamente la documentación del nuevo endpoint:
GET /api/posts/recent/Swagger UI y ReDoc listos para producción
Al usar drf-spectacular[sidecar], Django servirá automáticamente los archivos estáticos para
Swagger UI y ReDoc sin configuraciones adicionales.
Conclusión
drf-spectacular es actualmente la herramienta más sólida y moderna para documentar APIs
creadas con Django REST Framework. Te permite generar documentación OpenAPI 3 completa,
manteniendo compatibilidad con las versiones más recientes de Django y DRF.
- Documentación automática a partir de serializers y viewsets.
- Compatibilidad con Django 4 y 5.
- Soporte completo para Swagger UI y ReDoc.
- Permite añadir ejemplos, descripciones y seguridad personalizada.