FastAPI vs OpenAPI

A la hora de desarrollar una API, es esencial comprender el papel que desempeñan marcos como FastAPI y especificaciones como OpenAPI. Aunque ambos están interconectados, tienen objetivos distintos en el ciclo de vida del desarrollo de API.

Tabla de contenidos

¿Qué es FastAPI?

FastAPI es un framework web moderno y de alto rendimiento para construir APIs con Python, aprovechando las capacidades asíncronas para un rendimiento óptimo. Es fácil de usar para los desarrolladores, ya que proporciona documentación interactiva automática, validación y soporte para sugerencias de tipos de Python.

Características principales de FastAPI:

Alto rendimiento: Construido sobre Starlette para un manejo HTTP de alta velocidad.
Soporte asíncrono: Optimizado para operaciones asíncronas, lo que lo hace ideal para aplicaciones web modernas.
Documentación interactiva: Genera automáticamente la interfaz de usuario Swagger y la documentación ReDoc.
Seguridad de tipos: Utiliza sugerencias de tipos de Python para la validación de solicitudes y la generación de documentación.

¿Qué es OpenAPI?

OpenAPI, anteriormente conocida como Swagger Specification, es una especificación estándar del sector para describir API REST. Define la estructura de su API, incluidos los puntos finales, los esquemas de solicitud/respuesta y los métodos de autenticación, lo que permite la interoperabilidad entre diferentes herramientas y lenguajes de programación.

Características principales de OpenAPI:

Lenguaje agnóstico: Proporciona una forma estandarizada de describir las API independientemente de su implementación.
Ecosistema de herramientas: Soporta herramientas para el diseño de API, pruebas, documentación y generación cliente/servidor.
Formato legible por máquina: Las descripciones se escriben en YAML o JSON.
Documentación interactiva: Permite la generación automática de documentación interactiva.

FastAPI y OpenAPI: La conexión

FastAPI está diseñado para soportar OpenAPI de forma nativa, generando documentación compatible con OpenAPI de forma predeterminada. Esta sinergia permite a los desarrolladores:

Escribir código Pythonic limpio utilizando FastAPI.
Producir automáticamente especificaciones OpenAPI para documentación, validación y generación de clientes.

Implementación programática: FastAPI generando documentación OpenAPI

He aquí un ejemplo para ilustrar cómo FastAPI trabaja con OpenAPI para crear APIs:

Paso 1: Crear una aplicación FastAPI sencilla

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    """
    Get item details.

    - **item_id**: ID of the item to retrieve
    - **q**: Optional query string
    """
    return {"item_id": item_id, "q": q}

Paso 2: Acceder a la documentación generada automáticamente

Interfaz de usuario Swagger: Visita /docs (por ejemplo, http://127.0.0.1:8000/docs) para obtener documentación interactiva de la API basada en Swagger.
ReDoc: visita /redoc (por ejemplo, http://127.0.0.1:8000/redoc) para obtener una vista de la API basada en ReDoc.
Especificaciones OpenAPI sin procesar: Visita /openapi.json para obtener la especificación OpenAPI JSON sin procesar.

Personalización de OpenAPI en FastAPI

FastAPI ofrece flexibilidad para personalizar el esquema OpenAPI. Puede incluir metadatos, versiones y descripciones adaptadas a su API.

Ejemplo: Metadatos OpenAPI personalizados

app = FastAPI(
    title="My Custom API",
    description="This is a custom API description using FastAPI.",
    version="1.0.0"
)

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    """
    Retrieve a user by ID.
    """
    return {"user_id": user_id}

Al acceder a /docs, los metadatos personalizados aparecen en la interfaz de usuario Swagger.

Ampliación de OpenAPI con FastAPI

También puedes ampliar el esquema OpenAPI para necesidades específicas utilizando las capacidades de FastAPI.

Añadir etiquetas OpenAPI personalizadas

from fastapi import FastAPI, APIRouter

app = FastAPI()

user_router = APIRouter()

@user_router.get("/users/{user_id}", tags=["Users"])
async def get_user(user_id: int):
    """
    Retrieve user details.
    """
    return {"user_id": user_id}

app.include_router(user_router)

En el código anterior, el endpoint /users/{user_id} está categorizado bajo la etiqueta Users en la especificación OpenAPI.

Comparación entre FastAPI y OpenAPI

Conclusión

FastAPI y OpenAPI se complementan perfectamente en el desarrollo moderno de APIs. Mientras que FastAPI simplifica la creación de APIs con Python, OpenAPI estandariza la forma en que se describen las APIs. El uso de ambas garantiza API de alta calidad, escalables e interoperables.

Para los desarrolladores que trabajan con API basadas en Python, FastAPI ofrece lo mejor de ambos mundos al proporcionar una integración perfecta con OpenAPI, lo que le permite ofrecer API sólidas y bien documentadas sin esfuerzo.

PorJavier Calderon