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

¿Qué es Swagger-PHP y por qué usarlo?

Swagger-PHP es una potente biblioteca de PHP que genera automáticamente documentación para APIs REST en formato OpenAPI (anteriormente conocido como Swagger). En lugar de escribir la documentación manualmente en YAML o JSON, describes tu API directamente en el código usando anotaciones PHPDoc. La biblioteca analiza estas anotaciones y genera una especificación OpenAPI completa, que puedes visualizar con Swagger UI, ReDoc u otras herramientas.

¿Por qué es útil?

• Automatización: La documentación siempre está sincronizada con el código. Cambias un endpoint, actualizas la anotación y la documentación está lista.
• Estandarización: OpenAPI es el estándar industrial para describir APIs REST, compatible con cientos de herramientas.
• Ideal para frontend: Los desarrolladores de aplicaciones cliente pueden importar la especificación a Postman, Insomnia o generar código cliente automáticamente.
• Pruebas automatizadas: La especificación se puede usar para probar tu API de forma automática.
• Documentación interactiva: Swagger UI permite probar los endpoints directamente desde el navegador.

Instalación de Swagger-PHP

La instalación se realiza mediante Composer, el gestor de paquetes estándar de PHP. Abre la terminal en la raíz de tu proyecto y ejecuta:

composer require zircote/swagger-php

Si usas Laravel, Symfony u otro framework, la instalación es la misma. Tras instalarlo, aparecerá la carpeta vendor/zircote/swagger-php en tu proyecto.

Opcional: Para visualizar la documentación necesitarás Swagger UI. Puedes instalarlo con npm:

npm install swagger-ui-dist

O simplemente descargar la compilación lista desde el sitio oficial de Swagger.

Inicio rápido con ejemplo de código

Vamos a crear una API simple para gestionar una lista de tareas (Todo List) y generar su documentación.

Paso 1: Crea el archivo index.php con tu API:

<?php
/**
 * @OA\Info(
 *     title="API de Tareas",
 *     version="1.0.0",
 *     description="API simple para gestionar tareas"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="Servidor local"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="Obtener lista de todas las tareas",
 *     @OA\Response(
 *         response=200,
 *         description="Respuesta exitosa",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'Comprar leche', 'completed' => false],
        ['id' => 2, 'title' => 'Escribir artículo', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="Crear una nueva tarea",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="Tarea creada",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // Lógica para crear la tarea
    echo json_encode(['id' => 3, 'title' => 'Nueva tarea', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// Enrutamiento simple
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQ