Documentación automática de APIs con drf-spectacular
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.
Swagger es HERMOSO, lo use pila en el curso de FastAPI. Lo recomiendo a la n potencia.
esta genial si!
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!
En teoría lo tengo así, pero sigue todo agrupado en "API"
:/
Tanto Swager com Redoc se ven como buenas opciones para documentación. Aunque por gusto prefiero Redoc.
Me costo mucho pero lo logre jajajaaj todo era por que habia escrito mal los serializadores de bookings
Claro, a veces ese tipo de errores nos quita tiempo, en el mundo del desarrollo los llamamos: typos
Qué opinan de coreapi en comparación?
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!
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:
# schemas.pyfrom drf_spectacular.utilsimport(OpenApiResponse, extend_schema, extend_schema_view, inline_serializer,)def personal_appointment_list_by_patient_view_schema():returnextend_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
¿Como hago para mejorar la visualización de la documentación por cada entidad (clase)? Se ven todos los endpoints juntos:
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)
Me sirvió muchas gracias, anado que hay que colocarlo en el settings.py de doctor_app
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:
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 ?
