Swagger-PHP é sempre a primeira coisa que vem à mente ao pensar em gerar uma especificação Swagger para um projeto PHP. Então, o que é o Swagger-PHP? Como você cria especificações usando o Swagger-php? Neste artigo, abordaremos essas perguntas e apresentaremos os detalhes.

O que é o Swagger-PHP

swagger-PHP é uma ferramenta para gerar documentação de API usando Swagger (agora conhecido como a Especificação OpenAPI) em PHP. swagger-php ajuda os desenvolvedores PHP a criar documentação de API com base na especificação Swagger (OpenAPI). Esta ferramenta pode gerar especificações Swagger (OpenAPI) a partir de código PHP. Ela permite que os desenvolvedores definam endpoints de API, requisições e respostas no código e gerem automaticamente uma especificação Swagger (OpenAPI).

Recursos do Swagger-PHP

Swagger-PHP é uma ferramenta poderosa usada para gerar especificações para as versões OpenAPI 3.0 e 3.1. Também é capaz de registrar APIs usando código-fonte PHP. O atributo de anotação usado pelo Swagger-php pode ser blocos de documentação ou php 8.1, tornando-o altamente flexível e versátil.

Se você estiver trabalhando com blocos de documentação ou com a versão mais recente do PHP, o Swagger-php pode ajudar a otimizar seu processo de desenvolvimento de API e torná-lo mais eficiente no geral.

Como instalar e configurar o Swagger-PHP

Para começar a usar o Swagger-PHP, você precisa instalá-lo primeiro. O Swagger-PHP pode ser instalado usando o Composer, um gerenciador de dependências para PHP.

Para instalar o Swagger-PHP, execute o seguinte comando no seu terminal:

composer require zircote/swagger-php

Uma vez instalado, você pode começar a usar o Swagger-PHP para gerar documentação Swagger para sua API.

Em seguida, você precisa configurar o Swagger-PHP criando uma nova instância do Swagger e configurando-a com as informações da sua API. Aqui está um exemplo de como configurar o Swagger-PHP :

require_once('vendor/autoload.php');

use Swagger\Annotations as SWG;

/**
 * @SWG\Swagger(
 *     basePath="/api",
 *     schemes={"http", "https"},
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="Minha API",
 *         description="Documentação da API para Minha API",
 *         @SWG\Contact(name="Minha Empresa"),
 *         @SWG\License(name="MIT")
 *     )
 * )
 */

Neste exemplo, criamos uma nova instância do Swagger e a configuramos com as informações da nossa API, como o caminho base, esquemas e informações da API (versão, título, descrição, contato e licença).

Depois de configurar o Swagger-PHP, você pode começar a adicionar anotações Swagger ao seu código de API para gerar a documentação Swagger. Vamos cobrir isso em mais detalhes na próxima seção.

Criando Documentação Swagger com Swagger-PHP

Swagger-PHP é uma biblioteca PHP para gerar documentos Swagger. Nesta seção, aprenderemos como criar documentação Swagger usando o Swagger-PHP.

Passo 1. Definindo informações da API

Primeiro, precisamos definir as informações da API. Isso inclui o título, descrição, versão, etc. da API. O seguinte é um exemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'Minha API',
        'description' => 'Esta é uma documentação de API de exemplo.',
        'version' => '1.0.0'
    ]);

Passo 2. Definindo os endpoints da API

Em seguida, precisamos definir os endpoints da API. Isso inclui os métodos HTTP, caminhos, parâmetros e respostas para cada endpoint. O seguinte é um exemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'Minha API',
        'description' => 'Esta é uma documentação de API de exemplo.',
        'version' => '1.0.0'
    ])
    ->get('/usuarios', [
        'summary' => 'Obter uma lista de usuários.',
        'description' => 'Retorna uma lista de usuários.',
        'responses' => [
            '200' => [
                'description' => 'Uma lista de usuários.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/Usuario'
                    ]
                ]
            ]
        ]
    ])
    ->post('/usuarios', [
        'summary' => 'Criar um novo usuário.',
        'description' => 'Cria um novo usuário.',
        'parameters' => [
            [
                'name' => 'usuario',
                'in' => 'body',
                'description' => 'O usuário a ser criado.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/Usuario'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'O usuário criado.',
                'schema' => [
                    '$ref' => '#/definitions/Usuario'
                ]
            ]
        ]
    ]);

Passo 3. Definindo o modelo de dados

Finalmente, precisamos definir os modelos de dados. Isso inclui os atributos e tipos de cada modelo. O seguinte é um exemplo:

$swagger = \Swagger\Swagger::make()
    ->info([
        'title' => 'Minha API',
        'description' => 'Esta é uma documentação de API de exemplo.',
        'version' => '1.0.0'
    ])
    ->get('/usuarios', [
        'summary' => 'Obter uma lista de usuários.',
        'description' => 'Retorna uma lista de usuários.',
        'responses' => [
            '200' => [
                'description' => 'Uma lista de usuários.',
                'schema' => [
                    'type' => 'array',
                    'items' => [
                        '$ref' => '#/definitions/Usuario'
                    ]
                ]
            ]
        ]
    ])
    ->post('/usuarios', [
        'summary' => 'Criar um novo usuário.',
        'description' => 'Cria um novo usuário.',
        'parameters' => [
            [
                'name' => 'usuario',
                'in' => 'body',
                'description' => 'O usuário a ser criado.',
                'required' => true,
                'schema' => [
                    '$ref' => '#/definitions/Usuario'
                ]
            ]
        ],
        'responses' => [
            '200' => [
                'description' => 'O usuário criado.',
                'schema' => [
                    '$ref' => '#/definitions/Usuario'
                ]
            ]
        ]
    ])
    ->definitions([
        'Usuario' => [
            'type' => 'object',
            'properties' => [
                'id' => [
                    'type' => 'integer',
                    'format' => 'int64'
                ],
                'nome' => [
                    'type' => 'string'
                ],
                'email' => [
                    'type' => 'string'
                ]
            ]
        ]
    ]);

Passo 4. Exportando documentos Swagger

Finalmente, podemos gerar a documentação Swagger usando o seguinte código:

header('Content-Type: application/json');
echo $swagger->toJson();

Isso irá gerar um documento Swagger no formato JSON que pode ser usado para gerar documentação da API.

Integrando o Swagger UI com o Swagger-PHP

Para aproveitar ao máximo os benefícios da documentação Swagger, é importante ter uma interface amigável para visualizar e interagir com a documentação. É para isso que serve o Swagger-ui. O Swagger-UI é uma interface baseada na web que fornece uma experiência interativa para visualizar e testar a documentação Swagger.

Integrar o Swagger-UI com o Swagger-PHP é um processo simples. Primeiro, faça o download da versão mais recente do Swagger-UI no repositório oficial do GitHub. Em seguida, extraia o conteúdo do arquivo baixado para um diretório no seu servidor web.

Em seguida, crie um novo arquivo PHP que servirá como ponto de entrada para o Swagger-UI. Neste arquivo, inclua os arquivos CSS e JavaScript necessários para o Swagger-UI, bem como a biblioteca JavaScript Swagger-ui propriamente dita. Você também precisará incluir o arquivo JSON gerado pelo Swagger-PHP que contém a documentação da sua API.

<!DOCTYPE html>
<html>
<head>
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="path/to/swagger-ui.css">
  <script type="text/javascript" src="path/to/swagger-ui-bundle.js"></script>
  <script type="text/javascript" src="path/to/swagger-ui-standalone-preset.js"></script>
</head>
<body>
  <div id="swagger-ui"></div>
  <script type="text/javascript">
    window.onload = function() {
      // Construir um sistema
      const ui = SwaggerUIBundle({
        url: "path/to/swagger-json.php",
        dom_id: '#swagger-ui',
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        layout: "BaseLayout"
      })
    }
  </script>
</body>
</html>

No exemplo acima, substitua os placeholders path/to pelos caminhos reais para os arquivos CSS e JavaScript do Swagger-UI, bem como o arquivo JSON gerado pelo Swagger-PHP.

Depois de criar este arquivo, você pode acessar o Swagger-UI navegando até sua URL em seu navegador web. Você deve ver uma interface Swagger-ui totalmente funcional que exibe sua documentação de API e permite que você interaja com ela.

Em conclusão, integrar o Swagger-UI com o Swagger-PHP é um processo simples que melhora muito a usabilidade da sua documentação de API. Ao seguir os passos descritos acima, você pode facilmente criar uma interface amigável para a sua documentação de API que facilitará a compreensão e o uso da sua API pelos desenvolvedores.

Compartilhar especificações de API

Depois de gerar a especificação Swagger, muitas vezes a compartilho com os membros da minha equipe. Nessas ocasiões, frequentemente compartilhamos em formatos Swagger JSON ou OpenAPI yaml, mas isso parece um pouco desatualizado.

Aqui, o Apidog é a ferramenta de gerenciamento de API perfeita que gera instantaneamente especificações de API altamente legíveis com base em dados Swagger JSON ou YAML. Você também pode compartilhar facilmente esta especificação de API com a função de compartilhamento de API.

O Apidog também fornece várias funções como uma ferramenta de gerenciamento de ciclo de vida de API.

Design de API e geração de especificações: Apidog é a ferramenta de design de API mais fácil de usar, permitindo que você projete APIs intuitivamente sem código e gere confortavelmente especificações OpenAPI e Swagger.

Gerenciamento de API e testes unitários: O Apidog facilita muito os testes unitários, pois você pode gerenciar sua API de maneira eficiente, enviar solicitações de API e validar respostas.

Automação de Teste de API: O Apidog também oferece suporte a testes automatizados e está pronto para CI/CD. Usando essa função para definir o número de threads, etc., você pode implementar facilmente testes de carga de API e automação de testes de API.

Conclusão

Em conclusão, o Swagger-PHP é uma ferramenta poderosa para gerar documentação Swagger para APIs baseadas em PHP. Ela permite que os desenvolvedores documentem suas APIs facilmente e as tornem acessíveis a outros desenvolvedores. Além disso, a integração do Swagger-UI com o Swagger-php fornece uma interface amigável para explorar e testar APIs.

Aqui estão alguns recursos para aprendizado adicional sobre o Swagger-PHP:

Documentação oficial: https://zircote.github.io/swagger-php/
Repositório do GitHub: https://github.com/zircote/swagger-php
Swagger-ui: https://swagger.io/tools/swagger-ui/