Swagger-PHP para PHP: guía completa con ejemplos prácticos

1. ¿Qué es y para qué sirve?

Swagger-PHP es una potente biblioteca para el lenguaje PHP que permite generar automáticamente la especificación OpenAPI (anteriormente Swagger) de tu API REST a partir de anotaciones en el código. En lugar de escribir manualmente enormes archivos YAML o JSON describiendo todos los endpoints, parámetros, modelos de datos y respuestas, simplemente agregas comentarios especiales (anotaciones) directamente en los controladores, modelos y rutas de tu aplicación PHP. La biblioteca analiza estas anotaciones y crea una especificación OpenAPI completa y válida, que puedes exportar en formato JSON o YAML.

¿Para qué sirve? En el desarrollo web moderno, la API es la interfaz clave de interacción entre el frontend, las aplicaciones móviles y los servicios de terceros. Mantener la documentación actualizada es un dolor de cabeza constante. Swagger-PHP resuelve este problema vinculando la documentación directamente con el código fuente. Si cambias la lógica de un endpoint, cambias también la anotación que está junto a él. La documentación siempre refleja el comportamiento real de la API. Esto ahorra horas de trabajo, reduce errores de integración y hace que tu proyecto sea transparente para los nuevos desarrolladores.

Además, la especificación OpenAPI generada se puede usar con decenas de herramientas: Swagger UI (documentación interactiva donde puedes probar solicitudes directamente desde el navegador), generadores de SDK cliente para JavaScript, Python, Java y otros lenguajes, herramientas de prueba y validación (como Postman o Insomnia), y para la generación automática de servidores mock. Swagger-PHP es el estándar de facto para documentar APIs en PHP.

2. Instalación

La instalación se realiza a través de Composer, el gestor de paquetes estándar para PHP. Ejecuta el siguiente comando en la raíz de tu proyecto:

composer require zircote/swagger-php

Después de la instalación, aparecerá el directorio vendor/zircote/swagger-php en tu proyecto. La biblioteca requiere PHP versión 8.0 o superior (para soportar las anotaciones modernas de PHP 8 y atributos). Si usas una versión anterior de PHP, necesitarás la versión 3.x de la biblioteca, pero se recomienda encarecidamente migrar a PHP 8+ y usar la última versión de Swagger-PHP (4.x).

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear un controlador muy simple con un solo endpoint y generar su especificación OpenAPI.

Paso 1: Crea el archivo src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'Obtener usuario por ID',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'Respuesta exitosa',
        content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'id', type: 'integer'),
                new OA\Property(property: 'name', type: 'string'),
                new OA\Property(property: 'email', type: 'string')
            ]
        )
    )]
    public function getUser(int $id): array
    {
        // Aquí iría la lógica para obtener el usuario de la BD
        return [
            'id' => $id,
            'name' => 'Juan Pérez',
            'email' => 'juan@ejemplo.com'
        ];
    }
}

Paso 2: Crea un script para generar la especificación generar-docs.php

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OpenApi\Generator;

// Indicamos el directorio donde están nuestros controladores con anotaciones
$openapi = Generator::scan(['src/Controllers']);

// Guarda