Geração Swagger/OpenAPI para PHP: Ferramentas e Bibliotecas

Geração Swagger/OpenAPI para PHP: Visão geral completa das ferramentas

No desenvolvimento web moderno, criar documentação de API de qualidade tornou-se não apenas uma boa prática, mas uma necessidade. Swagger (agora conhecido como OpenAPI) é um padrão para descrever APIs RESTful que permite automatizar a geração de documentação, SDKs de cliente e interfaces de console de teste. Neste artigo, veremos em detalhes como usar Swagger/OpenAPI para projetos PHP, quais bibliotecas existem e como implementá-las corretamente.

O que é Swagger/OpenAPI?

OpenAPI Specification (OAS) é uma especificação que define um padrão para descrever APIs REST nos formatos JSON ou YAML. Ela permite:

• Gerar automaticamente documentação interativa (Swagger UI);
• Criar bibliotecas de cliente para várias linguagens de programação;
• Validar a correção de requisições e respostas;
• Integrar-se com pipelines de CI/CD.

Principais bibliotecas para PHP

Para trabalhar com OpenAPI em PHP, existem várias bibliotecas populares. Vamos analisar cada uma delas em detalhes.

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

Esta é a biblioteca mais popular e madura para gerar especificações OpenAPI a partir de anotações PHP. Ela permite descrever a API diretamente no código, facilitando a manutenção da documentação atualizada.

Instalação:

composer require zircote/swagger-php

Exemplo de uso:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="Minha API", *     version="1.0.0", *     description="Exemplo de API para demonstração do Swagger" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Servidor de produção" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="Obter lista de usuários",     *     @OA\\Response(     *         response=200,     *         description="Resposta bem-sucedida",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // Lógica para obter usuários    }

    /**     * @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 vazio para descrever o esquema    }}

// Geração da especificação$openapi = \\OpenApi\\Generator::scan(['/caminho/para/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

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

Esta biblioteca não apenas permite descrever APIs, mas também gerar automaticamente código de servidor com base na especificação OpenAPI. Ela é especialmente útil ao usar o princípio de desenvolvimento Design-First.

Instalação:

composer require thecodingmachine/openapi-server

Exemplo de geração de servidor:

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

// Carregar especificação$spec = json_decode(file_get_contents('openapi.json'), true);

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

// Processar requisição$response = $server->handle($request);?>

3. Swagger-UI para PHP

Para exibir documentação interativa, você pode usar o Swagger UI integrado. Existem várias formas de integração:

• Usando CDN: Conecte os arquivos CSS e JS do Swagger UI diretamente;
• Instalação local: