Skip to content

Capítulo 6.4: Documentación de API

Tiempo de estudio: 30 minutos

1. ¿Por qué es necesaria la documentación de API?

Imagine que le dan un mando de control de una nave espacial compleja sin ninguna etiqueta en los botones. Los pulsaría al azar, arriesgándose a activar la catapulta en lugar de encender la luz. La documentación de API son precisamente esas etiquetas e instrucciones.

Una buena documentación:

  • Ahorra tiempo: Los desarrolladores no necesitan adivinar qué endpoints existen, qué parámetros aceptan y qué devuelven.
  • Reduce errores: Una descripción clara de los formatos de datos y los códigos de error ayuda a evitar el uso incorrecto de la API.
  • Simplifica la integración: El equipo de frontend puede trabajar en paralelo con el equipo de backend, basándose en la documentación como un contrato.
  • Es su legado: Dentro de seis meses, se lo agradecerá a usted mismo cuando regrese al proyecto.

💡 Analogía espacial:

  • API = Sistema de control complejo de una estación espacial.
  • Documentación de API = Manual para astronautas. Describe:
  • Qué comando (endpoint) enviar para abrir la compuerta.
  • Qué parámetros (cuerpo de la solicitud) pasar para configurar el sistema de soporte vital.
  • Qué señales (respuestas de API) esperar a cambio.

2. Documentación en FastAPI: Magia automática

FastAPI hace que la documentación sea increíblemente sencilla. Genera automáticamente documentación interactiva basada en su código, utilizando los estándares de OpenAPI y Swagger UI.

Paso 1: Agregue metadatos a su aplicación

En main.py puede agregar descripciones que aparecerán en la documentación.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (código FastAPI)

app = FastAPI(
    title="SpaceAPI",
    description="""
API para la exploración de la galaxia. 🚀

Podrá:
* **Ver planetas**.
* **Agregar nuevos mundos** (se requiere autenticación).
    """,
    version="1.0.0",
    contact={
        "name": "Ingeniero Jefe del Centro de Control de Misión",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

Paso 2: Describa sus modelos y endpoints

Cuanto más detalladamente describa los modelos Pydantic y los parámetros de los endpoints, mejor será la documentación.

# En el archivo de modelos Pydantic o en main.py

class PlanetBase(BaseModel):
    name: str = Field(..., example="Tierra", description="Nombre del planeta")
    description: str = Field(..., example="Un planeta azul con vida diversa", description="Breve descripción")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # o from_attributes = True en Pydantic v2

# En el archivo de rutas
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="Obtener la lista de todos los planetas",
    description="Devuelve una lista de todos los planetas conocidos con paginación (en el futuro)."
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="Crear un nuevo planeta",
    responses={
        401: {"description": "Usuario no autorizado"},
        422: {"description": "Error de validación de datos"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...
  • Field(..., example="..."): Agrega ejemplos a la documentación.
  • summary: Descripción breve del endpoint.
  • description: Descripción detallada.
  • responses: Descripción de posibles códigos de respuesta, además del exitoso.

Paso 3: Abra la documentación en el navegador

Inicie su servidor FastAPI y abra dos URL mágicas:

  1. http://127.0.0.1:8000/docs — abrirá la documentación interactiva de Swagger UI. ¡Aquí no solo podrá leer, sino también probar sus endpoints directamente desde el navegador!
  2. http://127.0.0.1:8000/redoc — abrirá una vista alternativa de la documentación de ReDoc. Es menos interactiva, pero a menudo más legible.

3. Documentación en Laravel: Uso de paquetes de terceros

A diferencia de FastAPI, Laravel no genera documentación "de fábrica". Sin embargo, existen excelentes paquetes que lo hacen, analizando su código. El más popular es Scribe.

Paso 1: Instalación de Scribe 

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

Paso 2: Descripción de endpoints usando DocBlocks

Scribe lee los PHP DocBlocks (comentarios como /** ... */) sobre los métodos de su controlador.

Abra app/Http/Controllers/PlanetController.php:

// app/Http/Controllers/PlanetController.php

/**
 * @group Planetas
 * API para la gestión de planetas
 */
class PlanetController extends Controller
{
    /**
     * Obtener lista de planetas
     *
     * Devuelve una lista paginada de todos los planetas en la galaxia.
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * Crear un nuevo planeta
     *
     * @authenticated
     *
     * @bodyParam name string required Nombre del planeta. Example: Kepler-186f
     * @bodyParam description string required Descripción del planeta.
     * @bodyParam size_km integer required Diámetro en kilómetros. Example: 14000
     * @bodyParam is_habitable boolean ¿Es habitable el planeta? Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "Primer planeta confirmado del tamaño de la Tierra en la zona habitable de otra estrella.",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... y así sucesivamente para otros métodos
}

Etiquetas clave de Scribe:

  • @group: Agrupa los endpoints.
  • @unauthenticated / @authenticated: Indica si se necesita un token.
  • @bodyParam: Describe un parámetro en el cuerpo de la solicitud.
  • @response: Ejemplo de una respuesta exitosa.

Paso 3: Generación y visualización de la documentación

Cada vez que realice cambios en los DocBlocks, ejecute el comando:

php artisan scribe:generate
Scribe creará una página HTML estática con su documentación. Ábrala en: http://your-app-url/docs.

Cuestionario de refuerzo

1. FastAPI genera documentación basada en el estándar:

2. ¿Qué URL abre Swagger UI en FastAPI por defecto?

3. Paquete popular para generar documentación en Laravel:

4. En Scribe, la etiqueta utilizada para describir los parámetros del cuerpo de la solicitud es:

🚀 Resumen del capítulo:

Has creado documentación profesional, transformando tus APIs de "cajas negras" en herramientas comprensibles y fáciles de usar.

  • ✅ Has comprendido la importancia crítica de documentar APIs.
  • 🪄 Has aprendido a usar la generación automática de documentación en FastAPI.
  • ⚙️ Has dominado los fundamentos del paquete Scribe para documentar APIs en Laravel.
  • 🛰️ Te has asegurado de que una buena documentación es el mejor asistente para cualquier desarrollador.

Tus APIs no solo funcionan y están protegidas, sino que también están completamente listas para ser usadas por otros miembros del equipo. Queda un último paso, pero el más importante: la verificación de seguridad final.

📌 Verificación:

  • Para FastAPI: abre /docs en el navegador y prueba a ejecutar un GET-request a la lista de planetas directamente desde la interfaz de Swagger UI.
  • Para Laravel: ejecuta php artisan scribe:generate y abre /docs. Asegúrate de que los endpoints estén agrupados y que el método store tenga una descripción de los parámetros.