Documentación automática Swagger/OpenAPI

Acceso a /docs y /redoc

FastAPI genera automáticamente documentación interactiva para tu API sin necesidad de configuración adicional. Esta funcionalidad está disponible desde el momento en que creas tu primera aplicación y se actualiza dinámicamente conforme añades nuevos endpoints.

Documentación con Swagger UI

La interfaz Swagger UI está disponible en la ruta /docs de tu aplicación. Esta herramienta te permite visualizar todos los endpoints de tu API, sus parámetros, tipos de datos y respuestas esperadas de forma interactiva.

Para acceder a la documentación, inicia tu servidor FastAPI:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hola mundo"}

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

Con el servidor ejecutándose mediante uvicorn main:app --reload, navega a http://localhost:8000/docs en tu navegador. Verás una interfaz gráfica completa que muestra:

• Lista de todos los endpoints disponibles
• Métodos HTTP soportados por cada ruta
• Parámetros requeridos y opcionales
• Esquemas de datos de entrada y salida
• Códigos de respuesta HTTP

La característica más útil de Swagger UI es su capacidad para probar endpoints directamente desde el navegador. Cada endpoint incluye un botón "Try it out" que te permite:

• Introducir valores para los parámetros
• Ejecutar la petición contra tu API
• Ver la respuesta completa incluyendo headers y código de estado

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

@app.post("/items/")
def create_item(item: Item):
    return {"item": item, "message": "Item creado correctamente"}

Con este código, la documentación mostrará automáticamente el esquema del modelo Item, permitiendo que los usuarios vean exactamente qué campos son necesarios y sus tipos de datos.

Documentación con ReDoc

FastAPI también proporciona una segunda interfaz de documentación llamada ReDoc, accesible en /redoc. Esta alternativa ofrece una presentación más limpia y orientada a la lectura de la documentación.

ReDoc se caracteriza por:

• Diseño más minimalista y fácil de leer
• Mejor organización para APIs con muchos endpoints
• Navegación lateral que facilita el acceso rápido a diferentes secciones
• Presentación más profesional para compartir con clientes o equipos

Ambas interfaces se generan a partir de la misma especificación OpenAPI, por lo que contienen exactamente la misma información. La elección entre /docs y /redoc depende principalmente de tus preferencias de presentación y el uso que vayas a darle.

Información automática extraída

FastAPI extrae automáticamente información de tu código Python para generar la documentación:

• Tipos de parámetros definidos en las funciones
• Docstrings de las funciones como descripciones de endpoints
• Modelos Pydantic como esquemas de datos
• Códigos de respuesta especificados en los decoradores

@app.get("/users/{user_id}", response_model=dict)
def get_user(user_id: int):
    """
    Obtiene la información de un usuario específico.
    
    - **user_id**: ID único del usuario
    """
    return {"user_id": user_id, "name": "Usuario ejemplo"}

Este endpoint aparecerá en la documentación con la descripción del docstring, el parámetro user_id marcado como entero requerido, y el esquema de respuesta inferido del response_model.

La actualización en tiempo real es otra ventaja significativa: cualquier cambio en tu código se refleja inmediatamente en la documentación al recargar la página, manteniendo siempre sincronizada la documentación con la implementación actual de tu API.

Personalización básica de la documentación

FastAPI permite personalizar la apariencia y metadatos de la documentación automática sin complicaciones adicionales. Estas personalizaciones mejoran la presentación profesional de tu API y proporcionan información contextual importante para los usuarios.

Configuración de metadatos básicos

La forma más sencilla de personalizar la documentación es mediante los parámetros del constructor de FastAPI. Estos metadatos aparecen en la parte superior de ambas interfaces de documentación:

from fastapi import FastAPI

app = FastAPI(
    title="API de Gestión de Productos",
    description="Una API REST para gestionar productos y categorías",
    version="1.0.0"
)

@app.get("/products")
def get_products():
    return {"products": []}

Los parámetros más útiles para la personalización básica incluyen:

• title: Nombre principal que aparece en la documentación
• description: Descripción detallada de la funcionalidad de tu API
• version: Número de versión de tu API
• contact: Información de contacto del desarrollador o equipo

Información de contacto y licencia

Puedes añadir información profesional adicional que aparecerá en la documentación para facilitar el contacto y especificar términos de uso:

app = FastAPI(
    title="API de Inventario",
    description="Sistema de gestión de inventario para tiendas online",
    version="2.1.0",
    contact={
        "name": "Equipo de Desarrollo",
        "email": "dev@empresa.com",
    },
    license_info={
        "name": "MIT License",
        "url": "https://opensource.org/licenses/MIT",
    }
)

Esta información aparece en una sección dedicada de la documentación, proporcionando contexto profesional sobre quién mantiene la API y bajo qué términos se puede utilizar.

Personalización de tags para organización

Los tags permiten agrupar endpoints relacionados en la documentación, creando secciones organizadas que facilitan la navegación:

@app.get("/users", tags=["usuarios"])
def get_users():
    return {"users": []}

@app.post("/users", tags=["usuarios"])
def create_user():
    return {"message": "Usuario creado"}

@app.get("/products", tags=["productos"])
def get_products():
    return {"products": []}

Los endpoints se agrupan automáticamente por tags en la interfaz, creando secciones colapsables que mejoran significativamente la experiencia de navegación cuando tu API tiene muchos endpoints.

Descripciones personalizadas para endpoints

Además de los docstrings básicos, puedes proporcionar descripciones más detalladas y ejemplos de uso directamente en los decoradores:

@app.post(
    "/items/",
    tags=["items"],
    summary="Crear un nuevo item",
    description="Crea un nuevo item en el sistema con la información proporcionada",
    response_description="Item creado exitosamente"
)
def create_item(item: Item):
    return {"item": item}

Estos parámetros enriquecen la documentación con información contextual específica para cada endpoint, haciendo que la API sea más fácil de entender y utilizar.

Configuración de URLs personalizadas

Si necesitas cambiar las rutas por defecto de la documentación, FastAPI permite personalizar las URLs durante la inicialización:

app = FastAPI(
    title="Mi API",
    docs_url="/documentacion",  # Cambia /docs por /documentacion
    redoc_url="/api-docs",      # Cambia /redoc por /api-docs
    openapi_url="/api/openapi.json"  # Personaliza la URL del esquema OpenAPI
)

Esta funcionalidad es útil cuando necesitas integrar la documentación en un esquema de URLs específico o cuando quieres usar nombres más descriptivos en tu idioma preferido.

Desactivación selectiva de interfaces

En algunos casos, podrías querer desactivar una de las interfaces de documentación, manteniendo solo la que prefieras:

# Solo mantener Swagger UI
app = FastAPI(
    title="Mi API",
    redoc_url=None  # Desactiva ReDoc
)

# Solo mantener ReDoc
app = FastAPI(
    title="Mi API",
    docs_url=None  # Desactiva Swagger UI
)

Esta configuración es especialmente útil en entornos de producción donde quieres simplificar las opciones disponibles o cuando tienes preferencias específicas sobre qué interfaz utilizar.