Documentación automática de APIs con drf-spectacular

Clase 12 de 21 • Curso de Django Rest Framework

Resumen

La documentación de API clara y actualizada impulsa integraciones rápidas y seguras. Con Django, django-rest y drf-spectacular puedes generar una documentación automatizada basada en OpenAPI que se actualiza con tu código, mostrando endpoints, parámetros, respuestas y ejemplos sin esfuerzo.

¿Cómo crear documentación de API actualizada con Django y drf-spectacular?

Generar la doc automáticamente asegura consistencia y ahorra tiempo. Cada cambio en vistas y views se refleja en la documentación sin mantenimiento manual.

Objetivo: facilitar que otros sistemas y desarrolladores integren tu API sin fricción.
Inspiración: revisa cómo lo hace Stripe para entender buenas prácticas.
Ventaja clave: cuando modificas una vista, la documentación se actualiza sola.

¿Qué librerías y estándares intervienen?

drf-spectacular: genera el schema OpenAPI desde tu código.
Swagger: muestra la documentación como una página web interactiva con Try it out.
Redoc: ofrece otra UI con buscador y navegación clara.
OpenAPI: estándar que define endpoints, parámetros, respuestas y versiones en un archivo YAML.

¿Qué habilidades prácticas pones en juego?

Crear una app dedicada a docs para compartir la documentación.
Escribir descripciones con docstrings en clases de views (por ejemplo, listar citas médicas) para enriquecer el schema.
Probar endpoints desde el navegador con Try it out, sin usar Postman o curl.

¿Qué configuración clave necesitas en settings y urls?

El flujo es simple: crear la app de documentación, instalar y registrar drf-spectacular, definir el autoschema y exponer rutas.

¿Cómo preparar la app y el autoschema?

Crear una app llamada Docs enfocada en la documentación.
Agregarla a installed apps en Settings.
Registrar el autoschema de drf-spectacular en Settings, verificando que la variable no exista ya para evitar que Python tome la última configuración por error.

¿Cómo estructurar las rutas y los imports?

Crear un archivo urls.py en la app Docs con los endpoints de documentación.
Importar los paths correctos y añadirlos al urls.py del proyecto.
Mantener el orden de importaciones en Python: primero librerías de terceros, luego código de tu app.

Código citado del proceso de imports:

from django.urls import path

Evitar duplicar prefijos como "api" si ya están definidos en otras rutas del proyecto.

¿Qué ofrece Swagger y Redoc con OpenAPI?

Ambas UIs leen el schema OpenAPI para presentar endpoints, parámetros y ejemplos. Swagger además permite ejecutar pruebas con un clic.

¿Cómo funciona el archivo de schema?

Al abrir la ruta de API schema, se descarga un archivo YAML con la versión de OpenAPI.
Ese archivo describe todos los endpoints y la documentación agregada en el código Python.
Cualquier UI compatible con OpenAPI (Swagger o Redoc) puede usar el mismo archivo.

¿Qué verás en la interfaz y cómo documentas respuestas?

Para cada recurso: GET, POST, PUT y DELETE con parámetros y respuestas esperadas.
Puedes agregar una descripción en el docstring de la clase, por ejemplo: "Obtiene la lista de citas médicas programadas" y se mostrará en la UI.
Ejemplo de estado típico: 204 No Response en un DELETE, porque no retorna contenido.
Beneficios prácticos.
Documentación viva y sincronizada con el código.
Pruebas rápidas con Try it out desde el navegador.
Compatibilidad con múltiples UIs gracias a OpenAPI.

¿Ya incorporaste descripciones en tus views? Comparte dudas o mejoras que quisieras ver en la documentación de tus endpoints y el flujo con Swagger o Redoc.

Antonio Demarco Bonino

student•

Swagger es HERMOSO, lo use pila en el curso de FastAPI. Lo recomiendo a la n potencia.

Andres Trujillo

student•

esta genial si!

Andres Trujillo

student•

Chicos, si algunos cuando entra a la api y ve toda la doc de las apis adjuntas, pues puede que les pase lo siguiente:

deben quitar el indicardor de la api en urls.py de doctor app:

path("docs", include("docs.urls")) a path("", include("docs.urls")),
```con esto cuando vuelvan a entrar, pues les aparecerá la doc organizada!

JUAN ALEJANDRO PEREZ BERMUDEZ

student•

En teoría lo tengo así, pero sigue todo agrupado en "API"

Juan Camilo Jaramillo Tascón

student•

Tanto Swager com Redoc se ven como buenas opciones para documentación. Aunque por gusto prefiero Redoc.

Damian Rengifo

student•

Me costo mucho pero lo logre jajajaaj todo era por que habia escrito mal los serializadores de bookings

Luis Martinez

teacher•

Claro, a veces ese tipo de errores nos quita tiempo, en el mundo del desarrollo los llamamos: typos

Germán Salina

student•

Qué opinan de coreapi en comparación?

Andres Trujillo

student•

Pues acabo de echar le un ojo, y no fue tan agradable el ver la doc de core api, quizás la implementación sea diferente, si los pruebas nos comentas!

Carlos Rodríguez

student•

Yo en mis proyectos con DRF siempre uso @personal_appointment_list_by_patient_view_schema()class PersonalAppointmentListByPatientView(BasePermissionAPIView): permission_classes = [IsAuthenticated, PersonalAppointmentPermission]drf-spectacular documentado con decoradores de la siguiente manera:

# views.py
from .schemas import personal_appointment_list_by_patient_view_schema
  
@personal_appointment_list_by_patient_view_schema()
class PersonalAppointmentListByPatientView(BasePermissionAPIView):
    permission_classes = [IsAuthenticated, PersonalAppointmentPermission]

    def get_patient(self, patient_id: int):
        pass

    def get_query_params(self, data):
        pass

    def get_query(self, data, query_search, patient_id):
        pass

    def get_personal_appointment(self, query):
        pass

    def get(self, request: Request, patient_id: int):
        pass

# schemas.py
from drf_spectacular.utils import (
    OpenApiResponse,
    extend_schema,
    extend_schema_view,
    inline_serializer,
)

def personal_appointment_list_by_patient_view_schema():
    return extend_schema_view(
        get=extend_schema(
            operation_id="personal_appointment_list_by_patient",
            summary="Retrieve a list of personal appointments by patient",
            description="Retrieve a list of personal appointments by patient",
            tags=["Personal Appointment"],
            parameters=[PersonalAppointmentListSerializer],
            responses={
                200: OpenApiResponse(
                    response=inline_serializer(
                        name="PersonalAppointmentListByPatient",
                        fields=schema_pagination_serializer(PersonalAppointmentDetailSerializer),
                    ),
                    description="List of personal appointments by patient",
                ),
                400: OpenApiResponse(
                    response=schema_error_400,
                    description="Bad request",
                ),
                404: OpenApiResponse(
                    response=schema_error("Patient not found.", json_schema=True),
                    description="Patient not found",
                ),
            },
        ),
    )

Con esto nos da más flexibilidad en crear la documentación y agregar loss métodos que estemos suando

Ronaldo Jiménez

student•

¿Como hago para mejorar la visualización de la documentación por cada entidad (clase)? Se ven todos los endpoints juntos:

JUAN ALEJANDRO PEREZ BERMUDEZ

student•

SPECTACULAR_SETTINGS = {
    #DIOS COMO COSTÓ
    'SCHEMA_PATH_PREFIX': r"/api/",
}
```Lo solucioné como un champ, solo faltó leer bien la documentación (https://drf-spectacular.readthedocs.io/en/latest/settings.html)

DAVID CARMELO CABALLERO DUERTO

student•

Me sirvió muchas gracias, anado que hay que colocarlo en el settings.py de doctor_app

kolab Linkear

student•

En Django Rest Framework (DRF) puedes usar drf-spectacular para generar documentación OpenAPI detallada y personalizada. Configúralo de la siguiente manera

En settings de python

SPECTACULAR_SETTINGS = {

'TITLE': "Hospitals API's🏥",

'DESCRIPTION': 'Schedule your turn➕',

'VERSION': '0.0.1',

'SERVE_INCLUDE_SCHEMA': False,

}

Así se ve en web:

Oscar Urrutia Maciel

student•

Estaba revisando el codigo puesto en recursos y veo que no esta puesto el lookup_field, a mi me pincha si no lo pongo , por que en el codigo no esta ?

Esto se revisa mas adelante ?

Luis Martinez

teacher•

Puedes ajustar tu modelo usando el metodo clean_fields https://docs.djangoproject.com/en/5.1/ref/models/instances/#django.db.models.Model.clean_fields

Martin Esquite

student•

Que buen curso este, no me lo imagine de esta forma, ya tiene sus 5 estrellas

Manuel Galindo

student•

Cinco ventajas de documentar una API:

Facilita la comprensión: Ayuda a los desarrolladores a entender cómo usar la API.
Mejora la colaboración: Permite que diferentes equipos trabajen juntos de manera más eficiente.
Acelera el desarrollo: Reduce el tiempo necesario para integrar y utilizar la API.
Aumenta la calidad: Ayuda a identificar y corregir errores más rápidamente.
Promueve la adopción: Hace que la API sea más atractiva y accesible para nuevos usuarios.

Documentación automática de APIs con drf-spectacular

Fundamentos de Django Rest Framework

Django REST Framework para APIs escalables

Qué son las APIs y cómo funcionan

Configuración de Django REST Framework paso a paso

Django Rest: qué reutiliza de Django

Serializers Django: modelos a JSON fácil

Listado de pacientes con serializers en DRF

POST y GET en el mismo endpoint con Django REST

CRUD completo con PUT y DELETE en Django Rest

Cómo probar APIs con Postman y curl

Django Rest Framework: de funciones a vistas genéricas

Vistas genéricas en Django Rest Framework