O que é OpenAPI e Swagger?
OpenAPI é uma especificação aberta para descrever APIs REST de forma padronizada e legível por máquinas. Swagger, na verdade, é o nome da ferramenta que surgiu antes da especificação OpenAPI ser oficializada pela Linux Foundation. Hoje, Swagger refere-se ao conjunto de ferramentas do SmartBear que implementam a especificação OpenAPI, incluindo a famosa interface Swagger UI para visualizar e testar endpoints.
Quando você documenta uma API com OpenAPI/Swagger, está criando um contrato que descreve todos os endpoints, parâmetros, respostas, autenticação e modelos de dados. Esse documento pode ser consumido por clientes, geradores de código e ferramentas de teste automaticamente, economizando tempo e reduzindo erros de integração.
Configurando OpenAPI em um Projeto PHP
Instalação e Dependências
A forma mais prática de trabalhar com OpenAPI em PHP é usar a biblioteca zircote/swagger-php, que lê anotações diretamente do seu código. Instale via Composer:
composer require zircote/swagger-php
Também vamos usar o swagger-ui para visualizar a documentação:
composer require swagger-api/swagger-ui
Estrutura Básica com Anotações
No Swagger-PHP, você documenta sua API usando anotações PHP. Aqui está um exemplo de um controlador simples com dois endpoints:
<?php
namespace App\Controllers;
/**
* @OA\Info(title="API de Produtos", version="1.0.0")
* @OA\Server(url="http://localhost:8000", description="Servidor de desenvolvimento")
*/
class ProdutoController
{
/**
* @OA\Get(
* path="/api/produtos",
* summary="Lista todos os produtos",
* @OA\Response(
* response=200,
* description="Lista de produtos retornada com sucesso",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/Produto")
* )
* )
* )
*/
public function listar()
{
return json_encode([
['id' => 1, 'nome' => 'Notebook', 'preco' => 2500.00],
['id' => 2, 'nome' => 'Mouse', 'preco' => 50.00]
]);
}
/**
* @OA\Post(
* path="/api/produtos",
* summary="Criar novo produto",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(ref="#/components/schemas/ProdutoCreate")
* ),
* @OA\Response(
* response=201,
* description="Produto criado com sucesso",
* @OA\JsonContent(ref="#/components/schemas/Produto")
* )
* )
*/
public function criar()
{
$dados = json_decode(file_get_contents('php://input'), true);
return json_encode(['id' => 3, 'nome' => $dados['nome'], 'preco' => $dados['preco']]);
}
}
Definindo Schemas de Dados
Os schemas descrevem a estrutura dos seus objetos. Defina-os como classes com anotações:
<?php
namespace App\Models;
/**
* @OA\Schema(
* schema="Produto",
* type="object",
* required={"id", "nome", "preco"},
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="nome", type="string", example="Notebook"),
* @OA\Property(property="preco", type="number", format="float", example=2500.00)
* )
*/
class Produto
{
public int $id;
public string $nome;
public float $preco;
}
/**
* @OA\Schema(
* schema="ProdutoCreate",
* type="object",
* required={"nome", "preco"},
* @OA\Property(property="nome", type="string", example="Teclado"),
* @OA\Property(property="preco", type="number", format="float", example=150.00)
* )
*/
class ProdutoCreate
{
public string $nome;
public float $preco;
}
Gerando e Servindo a Documentação
Gerando o JSON do OpenAPI
Crie um script PHP na raiz do projeto (ex: openapi.php) que gera o arquivo de especificação:
<?php
require_once __DIR__ . '/vendor/autoload.php';
use OpenAPI\Generator;
$openapi = Generator::scan([__DIR__ . '/app']);
header('Content-Type: application/json');
echo json_encode($openapi->toArray(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
Execute via CLI: php openapi.php > openapi.json
Servindo Swagger UI
Copie o Swagger UI para sua pasta pública e crie um arquivo swagger.html:
<!DOCTYPE html>
<html>
<head>
<title>API Documentation</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.bundle.js"></script>
<script>
SwaggerUIBundle({
url: "/openapi.json",
dom_id: '#swagger-ui',
presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset]
});
</script>
</body>
</html>
Boas Práticas e Dicas Práticas
Documente parâmetros de query e path de forma clara. Se seu endpoint recebe filtros, declare-os explicitamente com suas restrições:
/**
* @OA\Get(
* path="/api/produtos",
* @OA\Parameter(
* name="categoria",
* in="query",
* description="Filtrar por categoria",
* @OA\Schema(type="string")
* ),
* @OA\Parameter(
* name="preco_max",
* in="query",
* description="Preço máximo",
* @OA\Schema(type="number", format="float")
* )
* )
*/
public function filtrar() { }
Sempre documente códigos de erro e exceções. Use diferentes status codes (400, 401, 404, 500) e descreva o que cada um significa em seu contexto. Mantenha a documentação atualizada junto com o código — quando você muda um endpoint, atualize a anotação imediatamente. Isso evita que a documentação fique obsoleta e confunda quem está consumindo a API.
Conclusão
Documentar APIs com OpenAPI/Swagger em PHP não é apenas bom para seus usuários — é um investimento na qualidade e manutenibilidade do seu código. Você aprende que a especificação OpenAPI funciona como um contrato vivo entre seu código e seus consumidores, mantendo tudo sincronizado. Swagger-PHP transforma suas anotações em documentação interativa automaticamente, economizando horas de esforço manual. Por fim, a Swagger UI oferece uma interface testável onde qualquer desenvolvedor pode explorar seus endpoints sem abrir uma única linha de código.