Skip to content

Capítulo 3.5: Documentación automática de Swagger

Tiempo de estudio: 30 minutos

1. Documentación de la API: Manual de operaciones de una estación espacial

Imagina que eres un astronauta nuevo llegando a la ISS. ¿Cómo sabrías qué interruptor controla qué y cómo manejar el brazo robótico? Necesitarías instrucciones detalladas y actualizadas.

La documentación de la API es un manual similar para los desarrolladores. Explica:

  • Qué "puertos de acoplamiento" (endpoints) están disponibles.
  • Qué "comandos" (métodos HTTP) se pueden enviar.
  • Qué "carga" (datos) se necesita transmitir.
  • Qué "telemetría" (respuestas) esperar.

El problema es que escribir la documentación manualmente es largo, aburrido y casi siempre se vuelve obsoleta.

💡 Analogía espacial:

La documentación manual son planos de papel que están en un archivo y no se actualizan después de la modernización de la estación. La documentación automática de FastAPI es un display interactivo en el Centro de Control de Misión que se actualiza en tiempo real después de cada cambio en la estación.

2. La Magia de FastAPI: ¿Cómo funciona?

FastAPI hace todo el "trabajo sucio" por ti, basándose en tu propio código. Escanea:

  1. Rutas: Todos los decoradores @app.get, @app.post, etc.
  2. Parámetros: Parámetros de ruta (ship_id: int) y de consulta.
  3. Modelos Pydantic: Tus "planos" (Spaceship, SpaceshipCreate).
  4. Cadenas de documentación (docstrings): Descripciones que escribes entre comillas triples.

Basándose en estos datos, FastAPI genera un esquema según el estándar OpenAPI (anteriormente conocido como Swagger), y luego lo muestra a través de dos hermosas interfaces.

3. Explorando el "display del Centro de Control de Misión": Swagger UI

Swagger UI es una interfaz interactiva que permite no solo leer la documentación, sino también probar la API directamente desde el navegador.

Abra http://127.0.0.1:8000/docs

Verá:

  • Lista de endpoints: Agrupados por etiquetas (por defecto, por nombre de recurso) y coloreados según los métodos HTTP.
  • Descripciones: Los textos de sus docstrings ("""...""") se muestran como descripciones de los endpoints.
  • Parámetros: Muestra qué parámetros (como ship_id) espera el endpoint, su tipo y si son obligatorios.
  • Cuerpo de la solicitud (Request Body): Para POST y PUT muestra el esquema JSON generado a partir de su modelo Pydantic (SpaceshipCreate).
  • Respuestas (Responses): Muestra los posibles códigos de estado y esquemas de respuesta, basados en response_model.
  • Botón "Try it out": Permite rellenar los parámetros y enviar una solicitud real a su servidor.

4. Mejorando la documentación: Etiquetas y descripciones

Hagamos nuestra documentación aún más profesional.

Paso 1: Añadiendo metadatos en FastAPI Al crear app, puede pasar información general sobre su API.

Cambie la línea app = FastAPI() en main.py: 

# main.py

app = FastAPI(
    title="API de Gestión de Flota",
    description="API para la gestión de flotas de naves espaciales.",
    version="1.0.0",
)
Ahora aparecerán el título y la descripción en la parte superior de su documentación.

Paso 2: Agrupando endpoints con etiquetas Puede añadir etiquetas a cada endpoint para agruparlos por significado.

Añada el parámetro tags en los decoradores: 

# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["Naves espaciales"])
# ...

# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["Naves espaciales"])
# ...

# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["Naves espaciales"])
# ...

# y así sucesivamente para PUT y DELETE
Ahora todas sus operaciones CRUD estarán agrupadas ordenadamente bajo el encabezado "Naves espaciales".

5. Vista alternativa: ReDoc

FastAPI proporciona otra interfaz para la documentación "de forma nativa" — ReDoc. Es menos interactiva, pero a menudo se considera más legible y es ideal para documentación estática.

Abra http://127.0.0.1:8000/redoc

Verá un diseño de tres columnas con navegación, descripciones de endpoints y esquemas de datos. Es una excelente manera de proporcionar documentación a sus "clientes" (por ejemplo, al equipo de frontend).

Cuestionario de repaso

1. FastAPI genera la documentación basándose en...

2. ¿Qué estándar subyace a la autodocumentación de FastAPI?

3. ¿En qué URL está disponible por defecto la documentación interactiva de Swagger UI?

4. El parámetro `tags` en el decorador `@app.get` se utiliza para:

5. ReDoc es...

🚀 Conclusión del capítulo:

Ha visto una de las "superpoderes" más potentes de FastAPI: la creación de documentación sin ningún esfuerzo.

  • 📖 Su API ahora tiene dos tipos de documentación actualizada: Swagger UI y ReDoc.
  • 🔬 La documentación es interactiva y permite probar la API al vuelo.
  • 🏷️ Aprendió a mejorarla con metadatos y etiquetas.

¡El manual de operaciones está listo y siempre actualizado! En el capítulo final de esta sección, aprenderemos a manejar las "anomalías espaciales": errores y datos incorrectos.

📌 Verificación:

  • Asegúrese de que en la dirección http://127.0.0.1:8000/docs se muestren el título, la descripción y los endpoints agrupados por etiquetas.
  • Verifique que su modelo Spaceship sea visible en la sección "Schemas".
  • Abra http://127.0.0.1:8000/redoc y evalúe la vista alternativa.

⚠️ Si los cambios no aparecen: - Asegúrese de haber guardado el archivo main.py. - Compruebe que el servidor uvicorn está ejecutándose con el flag --reload y se ha recargado exitosamente.