Geração Swagger/OpenAPI para PHP: melhores ferramentas e bibliotecas

Geração Swagger/OpenAPI para PHP: automatização da documentação de API

Swagger (agora OpenAPI) é um padrão para descrição de APIs RESTful que permite que desenvolvedores, clientes e ferramentas automatizadas entendam as capacidades do serviço sem acesso ao código-fonte. Para desenvolvedores PHP, a ferramenta chave é a biblioteca zircote/swagger-php (anteriormente conhecida como swagger-php), que gera automaticamente a especificação OpenAPI a partir de anotações no código.

O que é zircote/swagger-php?

É a principal biblioteca para geração de especificações OpenAPI em PHP. Ela analisa anotações PHPDoc em controladores, modelos e rotas, criando um arquivo JSON/YAML que pode ser usado para:

• Geração automática de documentação (Swagger UI, ReDoc)
• Geração de bibliotecas cliente para várias linguagens
• Testes de API (Postman, Insomnia)
• Validação de requisições e respostas

Instalação e configuração

Instalação via Composer:

composer require zircote/swagger-php

A configuração mínima para Laravel (ou qualquer framework) inclui a criação de anotações no controlador. Exemplo de um controlador simples com anotações OpenAPI:

<?php

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

use OpenApi\\Annotations as OA;

/** * @OA\\Info(title="My API", version="1.0.0") * @OA\\Server(url="https://api.example.com") */class UserController extends Controller{    /**     * @OA\\Get(     *     path="/api/users/{id}",     *     summary="Obter usuário por ID",     *     @OA\\Parameter(     *         name="id",     *         in="path",     *         required=true,     *         @OA\\Schema(type="integer")     *     ),     *     @OA\\Response(     *         response=200,     *         description="Resposta bem-sucedida",     *         @OA\\JsonContent(ref="#/components/schemas/User")     *     ),     *     @OA\\Response(response=404, description="Usuário não encontrado")     * )     */    public function show($id)    {        // lógica    }}

Geração da especificação

Para criar o arquivo OpenAPI, execute o comando:

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

Ou use código PHP:

<?php

use OpenApi\\Generator;

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

Funcionalidades avançadas

A biblioteca suporta:

• Esquemas aninhados — criação automática de modelos a partir de anotações
• Agrupamento de endpoints via @OA\\Tag
• Segurança — @OA\\SecurityScheme para JWT, OAuth2
• Exemplos de requisições — @OA\\RequestBody com exemplos

Exemplo de modelo com anotações:

<?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{    // propriedades}

Integração com frameworks

Para Laravel, existe o pacote darkaonline/l5-swagger, que adiciona:

• Geração automática a cada requisição
• Swagger UI integrado
• Configuração via arquivo config

Instalação:

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

Para Symfony, use nelmio/api-doc-bundle.

Compara