Generación Swagger/OpenAPI para PHP

Generación Swagger/OpenAPI para PHP: Resumen completo de herramientas

En el desarrollo web moderno, crear documentación de API de calidad se ha convertido no solo en una buena práctica, sino en una necesidad. Swagger (ahora conocido como OpenAPI) es un estándar para describir APIs RESTful que permite automatizar la generación de documentación, SDKs de cliente e interfaces de consola de prueba. En este artículo, analizaremos en detalle cómo usar Swagger/OpenAPI para proyectos PHP, qué bibliotecas existen y cómo implementarlas correctamente.

¿Qué es Swagger/OpenAPI?

OpenAPI Specification (OAS) es una especificación que define un estándar para describir APIs REST en formato JSON o YAML. Permite:

Generar automáticamente documentación interactiva (Swagger UI);
Crear bibliotecas de cliente para varios lenguajes de programación;
Validar la corrección de solicitudes y respuestas;
Integrarse con pipelines de CI/CD.

Bibliotecas principales para PHP

Para trabajar con OpenAPI en PHP, existen varias bibliotecas populares. Analicemos cada una de ellas en detalle.

1. Swagger-PHP (zircote/swagger-php)

Esta es la biblioteca más popular y madura para generar especificaciones OpenAPI a partir de anotaciones PHP. Permite describir la API directamente en el código, lo que facilita mantener la documentación actualizada.

Instalación:

composer require zircote/swagger-php

Ejemplo de uso:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="Mi API", *     version="1.0.0", *     description="API de ejemplo para demostrar Swagger" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Servidor de producción" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="Obtener lista de usuarios",     *     @OA\\Response(     *         response=200,     *         description="Respuesta exitosa",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // Lógica para obtener usuarios    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // Método vacío para describir el esquema    }}

// Generación de la especificación$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

Esta biblioteca no solo permite describir la API, sino también generar automáticamente código de servidor basado en la especificación OpenAPI. Es especialmente útil al utilizar el principio de desarrollo Design-First.

Instalación:

composer require thecodingmachine/openapi-server

Ejemplo de generación de servidor:

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// Carga de la especificación$spec = json_decode(file_get_contents('openapi.json'), true);

// Creación del servidor$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// Procesamiento de la solicitud$response = $server->handle($request);?>