Documentación Automática

Descripción

Una de las razones principales por las que FastAPI se convirtió en el framework dominante para APIs en Python es su documentación automática. Sin escribir una sola línea adicional, FastAPI genera dos interfaces interactivas donde puedes visualizar, explorar y probar todos tus endpoints directamente desde el navegador.

En esta cápsula explorarás /docs (Swagger UI) y /redoc (ReDoc), entenderás qué es OpenAPI y por qué importa, y aprenderás a personalizar la documentación de tu API con títulos, descripciones y metadatos. La documentación automática no es un extra — es una herramienta de desarrollo que usarás constantemente para probar endpoints sin necesidad de curl o Postman.

Al terminar, podrás probar cualquier endpoint de tu API directamente desde el navegador y personalizar cómo se presenta tu API a otros desarrolladores.

Swagger UI: /docs

Acceder a la documentación

Con tu servidor corriendo (uvicorn app.main:app --reload), abre en tu navegador:

http://127.0.0.1:8000/docs

Verás una interfaz interactiva con todos tus endpoints listados. Cada endpoint muestra:

• El verbo HTTP (GET, POST, etc.)
• La ruta (/health, /greet/{name}, etc.)
• Una descripción (si la configuraste)
• Los parámetros que acepta
• Un botón "Try it out" para probar el endpoint

Probar un endpoint desde /docs

1. Haz clic en cualquier endpoint (ej: GET /greet/{name})
2. Haz clic en "Try it out"
3. Escribe un valor en el campo name (ej: "FastAPI")
4. Haz clic en "Execute"

Verás tres secciones:

• Curl: El comando curl equivalente
• Request URL: La URL completa que se llamó
• Response body: La respuesta JSON del servidor
• Response headers: Headers HTTP de la respuesta

Curl:
curl -X 'GET' 'http://127.0.0.1:8000/greet/FastAPI' -H 'accept: application/json'

Response body:
{
  "message": "Hello, FastAPI!"
}

Response code: 200

Esto reemplaza la necesidad de usar curl o Postman para pruebas rápidas durante desarrollo. Es la herramienta que más usarás mientras construyes tu API.

ReDoc: /redoc

FastAPI también genera una segunda interfaz de documentación en:

http://127.0.0.1:8000/redoc

ReDoc presenta la misma información pero con un diseño diferente — más orientado a documentación de referencia que a testing interactivo.

Swagger UI vs ReDoc

¿Cuál usar? Durante desarrollo, usa /docs (Swagger UI) porque puedes probar endpoints. Para documentación que compartes con otros equipos (frontend, mobile), /redoc es más presentable.

OpenAPI: El estándar detrás de la documentación

¿Qué es OpenAPI?

OpenAPI (antes llamado Swagger Specification) es un estándar para describir APIs REST. Es un archivo JSON/YAML que define:

• Qué endpoints tiene tu API
• Qué parámetros acepta cada endpoint
• Qué respuestas retorna
• Qué tipos de datos usa

FastAPI genera este archivo automáticamente basándose en tu código Python.

Ver el schema OpenAPI

Accede a:

http://127.0.0.1:8000/openapi.json

Verás algo como esto (simplificado):

{
  "openapi": "3.1.0",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Root",
        "operationId": "root__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health Check",
        "operationId": "health_check_health_get",
        "responses": {
          "200": {
            "description": "Successful Response"
          }
        }
      }
    }
  }
}

Tanto Swagger UI como ReDoc leen este archivo para generar la interfaz visual. No son mágicos — están interpretando un JSON que FastAPI construye a partir de tu código.

Tu código Python
    ↓ FastAPI analiza decoradores, type hints, docstrings
openapi.json (generado automáticamente)
    ↓ Swagger UI y ReDoc lo interpretan
Interfaces visuales interactivas

Personalizar la documentación

Metadata de la API

Puedes personalizar el título, descripción y versión que aparecen en la documentación:

from fastapi import FastAPI

app = FastAPI(
    title="FastAPI Fundamentals API",
    description="API de ejemplo para aprender FastAPI desde cero. Cubre endpoints GET, path parameters y documentación automática.",
    version="1.0.0",
)


@app.get("/")
def root():
    return {"message": "Welcome to FastAPI Fundamentals API"}

Refresca /docs. Ahora verás:

• Título: "FastAPI Fundamentals API" (en vez de "FastAPI")
• Descripción: Tu descripción personalizada
• Versión: "1.0.0" (en vez de "0.1.0")

Documentar endpoints individuales

Cada endpoint puede tener su propia documentación:

@app.get(
    "/health",
    summary="Health Check",
    description="Verifica que el servicio está corriendo correctamente. Útil para load balancers y monitoring.",
    tags=["System"]
)
def health_check():
    return {"status": "healthy"}


@app.get(
    "/greet/{name}",
    summary="Greet User",
    description="Saluda al usuario por nombre. El nombre se pasa como path parameter.",
    tags=["Users"]
)
def greet(name: str):
    return {"message": f"Hello, {name}!"}

Esto agrega:

• summary: Título corto del endpoint (se muestra en la lista)
• description: Descripción detallada (se muestra al expandir)
• tags: Agrupa endpoints en secciones (ej: "System", "Users")

Tags para organizar endpoints

Los tags agrupan endpoints relacionados en la documentación:

from fastapi import FastAPI

app = FastAPI(
    title="FastAPI Fundamentals API",
    version="1.0.0",
)


@app.get("/", tags=["General"])
def root():
    return {"message": "Welcome"}


@app.get("/health", tags=["System"])
def health_check():
    return {"status": "healthy"}


@app.get("/about", tags=["System"])
def about():
    return {"name": "FastAPI Fundamentals API"}


@app.get("/greet/{name}", tags=["Users"])
def greet(name: str):
    return {"message": f"Hello, {name}!"}


@app.get("/items/{item_id}", tags=["Items"])
def get_item(item_id: int):
    return {"item_id": item_id}

En /docs, los endpoints se agrupan bajo sus respectivos tags:

General
  GET /

System
  GET /health
  GET /about

Users
  GET /greet/{name}

Items
  GET /items/{item_id}

Esto hace la documentación mucho más navegable cuando tienes decenas de endpoints.

Docstrings como documentación

FastAPI también usa los docstrings de tus funciones como descripción en la documentación:

@app.get("/greet/{name}", tags=["Users"])
def greet(name: str):
    """
    Saluda al usuario por su nombre.

    - **name**: El nombre de la persona a saludar
    - Retorna un mensaje personalizado en formato JSON
    - Soporta cualquier string como nombre
    """
    return {"message": f"Hello, {name}!"}

El docstring aparece como descripción del endpoint en Swagger UI y ReDoc, con formato Markdown renderizado.

Tip: Si defines tanto description en el decorador como un docstring, el docstring tiene prioridad.

Desactivar la documentación

En producción, puede que quieras desactivar la documentación por seguridad:

# Desactivar ambas interfaces
app = FastAPI(
    docs_url=None,      # Desactiva /docs
    redoc_url=None,     # Desactiva /redoc
    openapi_url=None,   # Desactiva /openapi.json
)

# O cambiar las URLs
app = FastAPI(
    docs_url="/api-docs",       # /docs → /api-docs
    redoc_url="/api-reference", # /redoc → /api-reference
)

Para esta guía, deja la documentación activa — es tu herramienta principal de desarrollo.

Comparación: Documentación manual vs automática

Trade-off: La documentación automática cubre el 90% de los casos. Para documentación de negocio (workflows, diagramas de arquitectura), necesitas documentación complementaria.

Conexión con proyecto

La documentación automática es parte integral de tu Hello World API (proyecto de este módulo):

• Usarás /docs para probar cada endpoint que crees
• Los tags organizarán tus endpoints por categoría
• La metadata (título, versión) dará identidad a tu API

En el Módulo 6 (proyecto final: To-Do List API), la documentación será clave para validar que todos los endpoints CRUD funcionan correctamente antes de entregar.

Troubleshooting

Problema 1: /docs muestra página en blanco

Causa: El navegador no puede cargar los assets de Swagger UI (CDN bloqueado o sin internet).

Solución:

# Instalar assets locales
pip install swagger-ui-bundle

# O verificar que tienes conexión a internet
# Swagger UI carga JavaScript desde un CDN por defecto

Problema 2: Un endpoint no aparece en /docs

Causa: El endpoint tiene un error de sintaxis o el decorador está mal formado.

Solución:

# ❌ Mal — falta paréntesis en el decorador
@app.get
def root():
    return {"message": "Hello"}

# ✅ Bien — decorador con ruta
@app.get("/")
def root():
    return {"message": "Hello"}

También verifica que el servidor se reinició (hot reload) y que no hay errores en la terminal de uvicorn.

Problema 3: La descripción no se muestra

Causa: Usas comillas simples en el docstring o el formato no es válido.

Solución:

# ✅ Usa triple comillas dobles para docstrings
@app.get("/endpoint")
def my_endpoint():
    """
    Esta descripción aparece en /docs.

    - Punto 1
    - Punto 2
    """
    return {"data": "value"}

Ejercicios

Ejercicio 1: Personalizar metadata (Fácil)

Configura tu aplicación FastAPI con título "Mi Primera API", versión "0.1.0", y una descripción que mencione que es un proyecto de aprendizaje. Verifica los cambios en /docs.

from fastapi import FastAPI

app = FastAPI(
    title="Mi Primera API",
    description="API de aprendizaje construida con FastAPI. Practica endpoints GET, path parameters y documentación automática.",
    version="0.1.0",
)


@app.get("/")
def root():
    return {"message": "Welcome to Mi Primera API"}

Ejercicio 2: Organizar con tags (Fácil)

Tienes 5 endpoints. Organízalos en tres tags: "General" (root), "System" (health, about), "Features" (greet, calculate).

from fastapi import FastAPI

app = FastAPI(title="Organized API", version="1.0.0")


@app.get("/", tags=["General"])
def root():
    return {"message": "Welcome"}


@app.get("/health", tags=["System"])
def health_check():
    return {"status": "healthy"}


@app.get("/about", tags=["System"])
def about():
    return {"name": "Organized API", "version": "1.0.0"}


@app.get("/greet/{name}", tags=["Features"])
def greet(name: str):
    return {"message": f"Hello, {name}!"}


@app.get("/calculate/{a}/{b}", tags=["Features"])
def calculate(a: int, b: int):
    return {"sum": a + b, "product": a * b}

Ejercicio 3: Documentar con summary y description (Medio)

Agrega summary y description a cada endpoint del ejercicio anterior. Usa el decorador, no docstrings.

@app.get(
    "/",
    tags=["General"],
    summary="Root Endpoint",
    description="Punto de entrada principal de la API. Retorna mensaje de bienvenida."
)
def root():
    return {"message": "Welcome"}


@app.get(
    "/health",
    tags=["System"],
    summary="Health Check",
    description="Verifica que el servicio está activo. Responde con status 'healthy' si todo funciona correctamente."
)
def health_check():
    return {"status": "healthy"}


@app.get(
    "/about",
    tags=["System"],
    summary="API Information",
    description="Retorna metadata de la API: nombre y versión actual."
)
def about():
    return {"name": "Organized API", "version": "1.0.0"}


@app.get(
    "/greet/{name}",
    tags=["Features"],
    summary="Greet User",
    description="Saluda al usuario por nombre. Acepta cualquier string como path parameter."
)
def greet(name: str):
    return {"message": f"Hello, {name}!"}


@app.get(
    "/calculate/{a}/{b}",
    tags=["Features"],
    summary="Calculate",
    description="Realiza operaciones matemáticas básicas con dos números enteros."
)
def calculate(a: int, b: int):
    return {"sum": a + b, "product": a * b}

Ejercicio 4: Documentar con docstrings y Markdown (Medio)

Reemplaza las descripciones del decorador por docstrings con formato Markdown (listas, negritas, código inline).

@app.get("/greet/{name}", tags=["Features"], summary="Greet User")
def greet(name: str):
    """
    Saluda al usuario por su nombre.

    **Parámetros:**
    - **name** (str): Nombre de la persona a saludar

    **Retorna:**
    - `message`: Saludo personalizado con el nombre proporcionado

    **Ejemplo:**
    - Request: `GET /greet/Maria`
    - Response: `{"message": "Hello, Maria!"}`
    """
    return {"message": f"Hello, {name}!"}


@app.get("/calculate/{a}/{b}", tags=["Features"], summary="Calculate")
def calculate(a: int, b: int):
    """
    Realiza operaciones matemáticas con dos números.

    **Parámetros:**
    - **a** (int): Primer operando
    - **b** (int): Segundo operando

    **Retorna:**
    - `sum`: Suma de a + b
    - `product`: Producto de a * b

    **Nota:** La división no se incluye para evitar errores con b=0.
    """
    return {"sum": a + b, "product": a * b}

Ejercicio 5: Comparar /docs, /redoc y /openapi.json (Medio)

Abre las tres URLs de tu API en pestañas separadas. Describe en tus propias palabras qué información comparten y qué las diferencia. Luego cuenta cuántos endpoints aparecen en openapi.json.

# Contar endpoints desde terminal:
curl -s http://127.0.0.1:8000/openapi.json | python -m json.tool | grep '"/' | wc -l

Resumen

• FastAPI genera dos interfaces de documentación automáticas: /docs (Swagger UI) y /redoc (ReDoc)
• /docs permite probar endpoints interactivamente con "Try it out" — tu herramienta principal durante desarrollo
• /redoc es mejor para documentación de referencia que compartes con otros equipos
• OpenAPI (/openapi.json) es el estándar detrás de ambas interfaces — un schema JSON generado desde tu código
• Puedes personalizar la documentación con metadata (title, description, version)
• Los tags agrupan endpoints en secciones para mejor organización
• Docstrings con Markdown se renderizan como descripción detallada de cada endpoint
• La documentación automática siempre está sincronizada con tu código — si cambias un endpoint, la docs se actualiza

Próxima cápsula: Proyecto Hello World API — Integrarás todo lo aprendido en un mini-proyecto con estructura profesional, múltiples endpoints organizados y documentación personalizada.

Recursos adicionales

1. FastAPI - Metadata and Docs URLs - Personalización oficial de documentación
2. Swagger UI - Official - La herramienta detrás de /docs
3. ReDoc - Official - La herramienta detrás de /redoc
4. OpenAPI Specification 3.1 - El estándar completo
5. FastAPI - Additional Responses - Documentar múltiples respuestas por endpoint
6. Swagger Editor - Editor visual de schemas OpenAPI