Generación Swagger/OpenAPI para PHP: mejores herramientas y bibliotecas

Generación Swagger/OpenAPI para PHP: automatización de la documentación de API

Swagger (ahora OpenAPI) es un estándar para describir APIs RESTful que permite a desarrolladores, clientes y herramientas automatizadas comprender las capacidades del servicio sin acceso al código fuente. Para desarrolladores PHP, la herramienta clave es la biblioteca zircote/swagger-php (anteriormente conocida como swagger-php), que genera automáticamente una especificación OpenAPI a partir de anotaciones en el código.

¿Qué es zircote/swagger-php?

Es la biblioteca principal para generar especificaciones OpenAPI en PHP. Analiza las anotaciones PHPDoc en controladores, modelos y rutas, creando un archivo JSON/YAML que se puede utilizar para:

• Generación automática de documentación (Swagger UI, ReDoc)
• Generación de bibliotecas cliente para varios lenguajes
• Pruebas de API (Postman, Insomnia)
• Validación de solicitudes y respuestas

Instalación y configuración

Instalación a través de Composer:

composer require zircote/swagger-php

La configuración mínima para Laravel (o cualquier framework) incluye la creación de anotaciones en el controlador. Ejemplo de un controlador simple con anotaciones OpenAPI:

<?php

namespace App\\Http\\Controllers\\Api;

use OpenApi\\Annotations as OA;

/** * @OA\\Info(title="Mi API", version="1.0.0") * @OA\\Server(url="https://api.example.com") */class UserController extends Controller{    /**     * @OA\\Get(     *     path="/api/users/{id}",     *     summary="Obtener usuario por ID",     *     @OA\\Parameter(     *         name="id",     *         in="path",     *         required=true,     *         @OA\\Schema(type="integer")     *     ),     *     @OA\\Response(     *         response=200,     *         description="Respuesta exitosa",     *         @OA\\JsonContent(ref="#/components/schemas/User")     *     ),     *     @OA\\Response(response=404, description="Usuario no encontrado")     * )     */    public function show($id)    {        // lógica    }}

Generación de la especificación

Para crear el archivo OpenAPI ejecute el comando:

vendor/bin/openapi src -o public/openapi.yaml

O use código PHP:

<?php

use OpenApi\\Generator;

$openapi = Generator::scan(['/path/to/project/src']);file_put_contents('public/openapi.json', $openapi->toJson());

Funcionalidades avanzadas

La biblioteca soporta:

• Esquemas anidados — creación automática de modelos a partir de anotaciones
• Agrupación de endpoints mediante @OA\\Tag
• Seguridad — @OA\\SecurityScheme para JWT, OAuth2
• Ejemplos de solicitudes — @OA\\RequestBody con ejemplos

Ejemplo de modelo con anotaciones:

<?php

/** * @OA\\Schema( *     schema="User", *     required={"id", "email"}, *     @OA\\Property(property="id", type="integer", format="int64"), *     @OA\\Property(property="email", type="string", format="email"), *     @OA\\Property(property="name", type="string"), *     @OA\\Property(property="created_at", type="string", format="date-time") * ) */class User{    // propiedades}

Integración con frameworks

Para Laravel existe el paquete darkaonline/l5-swagger, que añade:

• Generación automática en cada solicitud
• Swagger UI integrado
• Configuración a través de archivo de configuración

Instalación:

composer require darkaonline/l5-swaggerphp artisan vendor:publish --provider="L5Swagger\\L5SwaggerServiceProvider"

Para Symfony use nelmio/api-doc-bundle.

Comparación