Swagger-PHP para PHP: guia completo com exemplos práticos

1. O que é e para que serve

Swagger-PHP é uma biblioteca poderosa para a linguagem PHP que permite gerar automaticamente a especificação OpenAPI (anteriormente Swagger) da sua API REST com base em anotações no código. Em vez de escrever manualmente enormes arquivos YAML ou JSON descrevendo todos os endpoints, parâmetros, modelos de dados e respostas, você simplesmente adiciona comentários especiais (anotações) diretamente nos controllers, models e rotas da sua aplicação PHP. A biblioteca analisa essas anotações e cria uma especificação OpenAPI completa e válida, que pode ser exportada nos formatos JSON ou YAML.

Para que serve isso? No desenvolvimento web moderno, a API é a interface principal de interação entre o frontend, aplicativos móveis e serviços de terceiros. Manter a documentação atualizada é uma dor de cabeça constante. O Swagger-PHP resolve esse problema vinculando a documentação diretamente ao código-fonte. Se você altera a lógica de um endpoint, altera também a anotação ao lado dele. A documentação sempre corresponde ao comportamento real da API. Isso economiza horas de trabalho, reduz a quantidade de erros de integração e torna seu projeto transparente para novos desenvolvedores.

Além disso, a especificação OpenAPI gerada pode ser usada com dezenas de ferramentas: Swagger UI (documentação interativa onde você pode testar requisições diretamente do navegador), geradores de SDK clientes para JavaScript, Python, Java e outras linguagens, ferramentas de teste e validação (como Postman ou Insomnia), além da geração automática de servidores mock. O Swagger-PHP é o padrão de facto para documentar APIs PHP.

2. Instalação

A instalação é feita via Composer, o gerenciador de pacotes padrão para PHP. Execute o seguinte comando na raiz do seu projeto:

composer require zircote/swagger-php

Após a instalação, o diretório vendor/zircote/swagger-php será criado no seu projeto. A biblioteca requer PHP versão 8.0 ou superior (para suporte a atributos modernos do PHP 8). Se você estiver usando uma versão mais antiga do PHP, precisará da versão 3.x da biblioteca, mas é altamente recomendável migrar para PHP 8+ e usar a versão mais recente do Swagger-PHP (4.x).

3. Início rápido — exemplo mínimo funcional

Vamos criar um controller simples com um endpoint e gerar a especificação OpenAPI para ele.

Passo 1: Crie o arquivo src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'Obter usuário por ID',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'Resposta de sucesso',
        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
    {
        // Aqui deve estar a lógica para obter o usuário do banco de dados
        return [
            'id' => $id,
            'name' => 'João Silva',
            'email' => 'joao@exemplo.com'
        ];
    }
}

Passo 2: Crie o script para gerar a especificação gerar-docs.php

<?php

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

use OpenApi\Generator;

// Indica o diretório onde estão seus controllers com anotações
$openapi = Generator::scan(['src/Controllers']);

// Salva