Documentación de la API (Parte 1)#
Esta es la entrega número 17 de la serie de tutoriales de Django Ninja. Comenzamos el cuarto capítulo: Documentación de la API.
«Generar automáticamente la documentación de la API a partir del código» es una de las grandes ventajas competitivas de Django Ninja.
De hecho, la automatización de la documentación de la API fue precisamente la consideración principal para migrar mis proyectos laborales de Django REST framework a Django Ninja, y también la oportunidad con la que comencé a aprender Django Ninja.
Django Ninja ahorra una enorme cantidad de tiempo en la redacción manual de la documentación de la API (nosotros usábamos API Blueprint); en especial cuando cambian las especificaciones de la API, ya no es necesario modificar la documentación de forma síncrona, lo que reduce enormemente el esfuerzo de mantenerla.
Esto demuestra lo importante que es esta característica.
Consideraciones sobre el orden de enseñanza#
Entonces, ¿por qué no introduje la función de documentación de la API de Django Ninja hasta el artículo 17 de esta serie, es decir, en esta entrega?
La razón es que, para generar una documentación de API excelente, necesitas tener un cierto nivel de comprensión sobre el uso de los Schema. Por lo tanto, no tuve más remedio que ubicarlo después del tercer capítulo.
Ahora, comenzaremos a explorar cómo usar Django Ninja para producir documentación de API de alta calidad.
Todos los cambios de código de este artículo se pueden consultar en este PR.
Proyecto de ejemplo en GitHub#
Documentation as Code#
En el desarrollo de software moderno, «Documentation as Code» (DoC) es una filosofía cada vez más reconocida.
DoC consiste en integrar estrechamente la documentación con el código, haciendo que los desarrolladores utilicen «los mismos procesos y herramientas que en el desarrollo de código de software» para crear y mantener la documentación.
La documentación se actualiza automáticamente con los cambios de código, manteniendo una coherencia absoluta en todo momento.
Esto no solo aumenta la eficiencia del desarrollo, sino que también reduce las dificultades de comunicación o malentendidos causados por documentación desactualizada.
La función de generación automática de documentación de Django Ninja es, sin duda, una puesta en práctica del espíritu de «Documentation as Code».
Al escribir código como rutas de la API, funciones view, Schema, etc., podemos generar automáticamente documentación que cumple con el estándar OpenAPI; cuando el código cambia, estos documentos reflejan automáticamente los resultados del cambio, sin necesidad de mantenimiento manual.
Dos aspectos clave de la documentación automatizada de API en Django Ninja#
En Django Ninja, para generar documentación de API de alta calidad, se abarcan principalmente dos aspectos clave:
- Configuración de Django Ninja: Django Ninja viene con bastantes configuraciones para controlar los detalles de la documentación de la API, lo cual es el enfoque de este artículo.
- Configuración de Pydantic: Este será el tema de la siguiente entrega, donde explicaremos cómo definir eficazmente los Schema para que diversos detalles se presenten automáticamente en la documentación de la API.
Al llegar aquí, ¿no sientes un poco de entusiasmo? ☺️
Estado actual de la documentación de la API del proyecto#
Antes de empezar a mejorar drásticamente la calidad de la documentación, echemos un vistazo a lo «básica» que es la documentación de la API actual.
Tras iniciar el servidor de Django, visita la siguiente URL para ver la documentación actual de la API:
El contenido de la documentación actual es el siguiente:
Haremos un breve análisis desde la perspectiva de «si es útil y fácil de leer para los desarrolladores».
Análisis del problema#
En primer lugar, ¡no tiene agrupaciones!
Las API de las aplicaciones user y post de Django están todas mezcladas, y a medida que haya más y más API, resultará sumamente desordenado. Este es el problema que se debe resolver con mayor prioridad.
En segundo lugar, las descripciones de la API como «Get Users» o «Create Post» se convierten claramente de forma automática a partir del nombre de la función view. La información es limitada, no es lo bastante coloquial ni detallada; en pocas palabras, no es suficientemente «amigable para el lector».
Hagamos clic en la única API POST para ver su contenido:
La explicación en la página interna contiene «Crear publicación», la cual en realidad se obtiene del docstring de la función view:
@router.post(path='/posts/')
def create_post(...) -> tuple[int, dict]:
"""
Crear publicación
"""
...
Veamos de nuevo el ejemplo del cuerpo (body) de la solicitud HTTP:
Solo podemos decir que dista de ser ideal; ejemplos como "string" solo representan el «tipo», sin simular el título o el contenido de una publicación del mundo real.
Los problemas mencionados son precisamente los puntos clave que necesitamos mejorar en la documentación de la API.
Entre ellos, los ejemplos del cuerpo de la solicitud están relacionados con la configuración del Schema, que será el núcleo de la entrega siguiente.
En este artículo, nos enfocaremos primero en la configuración de Django Ninja; presentémoslas una a una.
1. Uso de Tags para agrupar las API#
Lo primero que debemos resolver es el problema de la agrupación (clasificación) de las API.
Para que la estructura del documento sea más clara, Django Ninja admite el uso de Tags para agrupar las API. Esto no solo ayuda a organizar la documentación, sino que también permite a los desarrolladores u usuarios encontrar más rápido la API que necesitan.
La agrupación por Tags se puede configurar en dos lugares.
Agrupación en el router de primer nivel#
La práctica más común es configurarlo en el router de primer nivel:
# NinjaForum/api.py
api.add_router(prefix='', router='user.api.router', tags=['User'])
api.add_router(prefix='', router='post.api.router', tags=['Post'])
Porque las API de la misma aplicación de Django suelen pertenecer al mismo grupo.
Agrupación en el decorador de ruta#
También se puede configurar la agrupación en el decorador de ruta, pero considero que esto pertenece a casos relativamente «excepcionales», utilizados principalmente para:
- El proyecto completo solo tiene una aplicación de Django.
- La misma aplicación de Django necesita diferentes agrupaciones.
Por ejemplo, en el siguiente ejemplo, no se distinguen aplicaciones de Django, pero sí existe la necesidad de agrupar:
from ninja import NinjaAPI
api = NinjaAPI()
@api.get("/users/", tags=["User"])
def get_users(request):
...
@api.post("/posts/", tags=["Post"])
def create_post(request, title: str):
...
En la mayoría de los casos, recomiendo agrupar en el router de primer nivel y listo.
De lo contrario, como en el ejemplo anterior, marcar uno por uno resulta un poco laborioso de implementar.
2. Configuración de documentación en el decorador de ruta#
El decorador de ruta de Django Ninja no solo permite configurar la ruta básica de la API, sino que también te permite añadir textos descriptivos de la API, los cuales se reflejarán directamente en la documentación generada.
A través de estas configuraciones, puedes agregar explicaciones a los parámetros, respuestas e incluso la intención de la API, haciendo la documentación más completa.
Mediante los parámetros description y summary, puedes proporcionar descripciones para cada ruta de la API. Sin embargo, description sobrescribirá el efecto de «convertir docstrings en descripciones de la API» mencionado antes, por lo que habitualmente solo escribo summary.
¡Después de todo, al escribir Python, los docstrings son indispensables!
El código es el siguiente:
@router.get(..., summary='Obtener lista de publicaciones')
def get_posts(...) -> QuerySet[Post]:
"""
Obtener lista de publicaciones
"""
...
Efectos reales de mejora hasta este punto: (agrupación, descripción de la API)
¡Está muy bien!
3. Configuración de NinjaAPI#
Puedes personalizar algunos detalles globales de la documentación de la API mediante la inicialización de la clase NinjaAPI. Por ejemplo:
# NinjaForum/api.py
from ninja import NinjaAPI
api = NinjaAPI(
title="Ninja Forum API",
version="1.0",
description="Esta es la documentación de la API de Ninja Forum, como referencia para los lectores"
)
Efecto real correspondiente:
Las opciones de inicialización de NinjaAPI son muy variadas; algunas de ellas podrían ser las que necesitas.
Este es solo un ejemplo sencillo; para conocer más detalles de configuración, puedes consultar la documentación.
Resumen#
En este artículo exploramos las configuraciones comunes para la generación automática de la documentación de API en Django Ninja, permitiendo llevar a la práctica el espíritu de «Documentation as Code»: el código y la documentación pueden mantenerse alineados fácilmente, reduciendo la molestia del mantenimiento manual.
Sin embargo, la calidad de la documentación de la API también depende de cómo definamos los detalles dentro de los Schema.
En la siguiente entrega, profundizaremos en este tema, explicando cómo proporcionar ejemplos de documentación de alta calidad a través de los parámetros de Field en Pydantic, elevando aún más la legibilidad y claridad de la documentación de la API.