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.
