Swagger-PHP para PHP: guia completo com exemplos

O que é Swagger-PHP e para que serve?

Swagger-PHP é uma poderosa biblioteca PHP para geração automática de documentação de API REST no formato OpenAPI (anteriormente conhecido como Swagger). Em vez de escrever a documentação manualmente em YAML ou JSON, você descreve a API diretamente no código usando anotações PHPDoc. A biblioteca analisa essas anotações e gera uma especificação OpenAPI completa, que pode ser visualizada com Swagger UI, ReDoc ou outras ferramentas.

Para que serve?

\n
• Automação: A documentação está sempre sincronizada com o código. Alterou um endpoint — atualizou a anotação, e a documentação está pronta.
\n
• Padronização: OpenAPI é o padrão industrial para descrição de APIs REST, suportado por centenas de ferramentas.
\n
• Conveniência para o frontend: Desenvolvedores de aplicações cliente podem importar a especificação para Postman, Insomnia ou gerar código cliente.
\n
• Testes: A especificação pode ser usada para testes automáticos da API.
\n
• Documentação interativa: Swagger UI permite testar endpoints diretamente do navegador.
\n

Instalação do Swagger-PHP

A instalação é feita via Composer — o gerenciador de pacotes padrão para PHP. Abra o terminal no diretório raiz do seu projeto e execute:

composer require zircote/swagger-php

Se você usa Laravel, Symfony ou outro framework, a instalação não difere. Após a instalação, a pasta vendor/zircote/swagger-php aparecerá no seu projeto.

Adicional (opcional): Para visualizar a documentação, você precisará do Swagger UI. Pode instalá-lo via npm:

npm install swagger-ui-dist

Ou simplesmente baixe a compilação pronta do site oficial do Swagger.

Início rápido com exemplo de código

Vamos criar uma API simples para gerenciar uma lista de tarefas (Todo List) e gerar a documentação para ela.

Passo 1: Crie o arquivo index.php com sua API:

<?php\n/**\n * @OA\\Info(\n *     title="Todo API",\n *     version="1.0.0",\n *     description="API simples para gerenciamento de tarefas"\n * )\n * @OA\\Server(\n *     url="http://localhost:8000",\n *     description="Servidor local"\n * )\n */\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Get(\n *     path="/tasks",\n *     summary="Obter lista de todas as tarefas",\n *     @OA\\Response(\n *         response=200,\n *         description="Resposta bem-sucedida",\n *         @OA\\JsonContent(\n *             type="array",\n *             @OA\\Items(ref="#/components/schemas/Task")\n *         )\n *     )\n * )\n */\nfunction getTasks() {\n    $tasks = [\n        ['id' => 1, 'title' => 'Comprar leite', 'completed' => false],\n        ['id' => 2, 'title' => 'Escrever artigo', 'completed' => true]\n    ];\n    header('Content-Type: application/json');\n    echo json_encode($tasks);\n}\n\n/**\n * @OA\\Post(\n *     path="/tasks",\n *     summary="Criar nova tarefa",\n *     @OA\\RequestBody(\n *         required=true,\n *         @OA\\JsonContent(ref="#/components/schemas/TaskInput")\n *     ),\n *     @OA\\Response(\n *         response=201,\n *         description="Tarefa criada",\n *         @OA\\JsonContent(ref="#/components/schemas/Task")\n *     )\n * )\n */\nfunction createTask() {\n    // Lógica de criação da tarefa\n    echo json_encode(['id' => 3, 'title' => 'Nova tarefa', 'completed' => false]);\n}\n\n/**\n * @OA\\Schema(\n *     schema="Task",\n *     @OA\\Property(property="id", type="integer"),\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property="completed", type="boolean")\n * )\n * @OA\\Schema(\n *     schema="TaskInput",\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property