flight php swagger
v0.6.2
Microestrutura de vôo incluída com Swagger, PHPUnit e outros utilitários úteis. Projetado para ajudar a iniciar o desenvolvimento de APIs construídas com as ferramentas mencionadas, incluindo a configuração básica do projeto, rotas e modelos de teste, bem como o modelo para testes unitários.
Este guia pressupõe que você esteja usando atualmente (ou planejando usar) as seguintes tecnologias em seu projeto:
PHP 7.1+
Compositor
Xdebug (obrigatório se você planeja usar PHPUnit)
Primeiro, certifique-se de ter instalado e configurado um servidor web em execução (como Apache) com PHP 7.1 ou superior.
Use composer para baixar o esqueleto do projeto, instalar todas as dependências necessárias e executar os testes de unidade de amostra:
composer create-project tribeos/flight-php-swagger path/to/project
Como o Flight depende do módulo mod_rewrite do Apache 2 para funcionar, você deve primeiro habilitá-lo via a2enmod e então reiniciar o servidor:
sudo a2enmod rewrite
sudo systemctl restart apache2
Depois, você também deve editar o arquivo de configuração padrão do Apache, pois inicialmente proíbe o uso de um arquivo .htaccess para aplicar regras de reescrita. O arquivo de configuração geralmente está localizado em /etc/apache2/apache2.conf . Nele, localize o bloco referente ao diretório /var/www e certifique-se de que AllowOverride esteja configurado como All e que você Require all granted .
<Diretório /var/www/>Opções Índices FollowSymLinksAllowOverride AllRequire all concedido </Diretório>
Após salvar as alterações, reinicie o servidor Apache.
Caso você tenha ou queira ter múltiplas configurações de site, você também pode habilitar regras de reescrita por site, editando o arquivo de configuração desejado em /etc/apache2/sites-available . Você pode consultar o tutorial a seguir para obter mais informações.
Nota : As instruções acima mencionadas assumem que você está usando uma distribuição Ubuntu. Caso você esteja usando um sistema operacional diferente, consulte o tutorial apropriado sobre como ativar o módulo de reescrita.
Windows (WAMP/XAMPP)
CentOS
O projeto e suas dependências requerem a instalação de certas extensões PHP. Extensões comuns que podem estar faltando podem ser algumas das seguintes:
| Emitir | Solução |
|---|---|
mbstring | sudo apt install php-mbstring |
problemas relacionados com zip e unzip | sudo apt install zip unzip php-zip |
Nota : Tal como acontece com a seção anterior do Apache 2, estas instruções estão relacionadas às distribuições do Ubuntu. Consulte um comando alternativo apropriado se estiver usando um sistema operacional diferente.
Terminada a instalação, você encontrará esta estrutura em seu projeto:
path/to/project ├── app │ ├── models │ │ └── SampleModel.php │ ├── routes │ │ ├── FlightSetup.php │ │ └── SampleRoute.php │ └── utils │ └── Validator.php ├── config │ ├── config.php │ └── config.sample.php ├── docs ├── logs │ └── .htaccess ├── tests │ ├── build │ └── unit │ └── SampleTest.php ├── vendor ├── .gitignore ├── .htaccess ├── autoload.php ├── composer.json ├── composer.lock ├── index.php ├── LICENSE ├── phpunit.xml └── README.md
Resumo dos principais componentes do projeto:
app : a pasta principal do aplicativo
models : modelos usados para solicitações/respostas
routes : definição de rotas API
utils : utilitários de aplicação, como validadores e registradores
config : arquivo(s) de configuração
docs : arquivos de documentação do Swagger
logs : armazenamento de logs
tests : pasta de testes do aplicativo
build : quaisquer arquivos compilados resultantes de testes de formulário (cobertura de código, etc.)
src : testar arquivos de origem
vendor : localização de todas as bibliotecas e código de terceiros
autoload.php : Um arquivo de inicialização que carrega as dependências do Composer e inclui todos os outros arquivos do projeto
index.php : ponto de entrada da API
phpunit.xml : configuração de teste PHPUnit
Todas as configurações principais relacionadas ao projeto (e a documentação do Swagger) são tratadas dentro do arquivo config/config.php . Altere/adicione as constantes de configuração de acordo com as necessidades do seu projeto.
Outro arquivo importante é index.php , que serve como ponto de entrada da API. Requer o arquivo autoload.php , que contém o código para carregar as dependências do Composer, bem como todos os outros arquivos de projeto necessários. Além disso, inicia o framework Flight. Os arquivos importados por padrão são todos models , routes e utils , bem como o arquivo de configuração do projeto ( config/config.php ), arquivo de configuração Swagger-PHP ( docs/swagger.php ) e o vendor/autoload.php do Composer. Altere/adicione arquivos a serem importados de acordo com a necessidade do seu projeto.
Flight é uma estrutura PHP extensível e fácil de usar que permite a criação rápida de APIs web RESTful. Ele permite que você crie endpoints de API detalhados e funcionais, juntamente com funcionalidades de middleware e a capacidade de substituir/criar métodos personalizados.
Voo::route('GET /amostra/@valor', function($valor) {
Voo::json([ 'valor_amostra' => $valor ]);
}); Todo o roteamento do projeto é feito via Flight. A configuração inicial do voo ( FlightSetup.php ), bem como todas as rotas do projeto são tratadas dentro da pasta routes e podem ser alteradas para atender às suas necessidades.
Extensa documentação de uso e exemplos sobre o Flight estão disponíveis na página inicial do Flight - área "Aprender". Para obter mais detalhes sobre a estrutura do Flight em si, você pode visitar seu repositório GitHub.
Depois de criar uma rota na pasta routes , você pode começar a escrever e gerar documentação OpenAPI para sua API RESTful.
A documentação é escrita dentro de DocBlocks , também conhecidos como blocos de comentários PHP, acima da rota correspondente.
/** * @OAGet( * path="/sample/route", * tags={"sample"}, * summary="Uma rota de amostra.", * @OAResponse( * response=200, * description="A resposta de exemplo." * ), * security={ * {"api_key": {}} * } * )*/Você pode definir o caminho, tags, breve resumo, parâmetros, valores de parâmetros padrão, corpo da solicitação, respostas disponíveis, autenticação de segurança e inúmeras outras opções para cada endpoint RESTful.
A configuração geral do Swagger, como nome do projeto, autor(es) do projeto, URL do servidor API, pastas de especificação, etc. pode ser encontrada e configurada em config/config.php , na área "Constantes de configuração do Swager" .
O esqueleto do projeto vem acoplado à pasta docs , que contém todos os arquivos necessários para a documentação do Swagger (arquivos de configuração do PHP, HTML e CSS). A documentação é acessada navegando até a rota raiz ( / ) do seu projeto através de um navegador.
Para obter mais informações sobre o Swagger em geral e o padrão OpenAPI, consulte a página inicial oficial do Swagger. Extensa documentação de uso e exemplos relacionados à implementação do PHP estão disponíveis na página oficial do swagger-php.
O projeto vem com http-logger, que é um registrador de solicitações, respostas e erros HTTP, que (por padrão) registrará todas as solicitações recebidas e sua resposta correspondente em logs/debug.log , como valores separados por tabulação (TSV). Informações detalhadas do registrador e detalhes de configuração podem ser encontradas na página do GitHub.
O logger requer a localização do arquivo de log (que é configurado por padrão através de uma constante em config/config.php ). Além disso, para utilizar totalmente os recursos do logger, o manipulador de erros interno do Flight deve ser desabilitado (se habilitado, ele detectará certos tipos de erros antes do http-logger).
/* Desativa o registrador de erros interno do FlightPHP. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Obtenha e use o logger */$logger = HttpLogger::get();$logger->log(); O registrador é incluído por meio de routes/FlightSetup.php e configurado dentro da função de middleware Flight Flight::after() , que é executada após cada solicitação (para que seja capaz de buscar a resposta apropriada). Você poderá alterar as funcionalidades do logger, bem como as rotas que ele irá monitorar, conforme sua divulgação.
Flight::output() Flight::output() é um método mapeado personalizado que combina as funcionalidades de Flight::json() (saída de resposta JSON) e o HTTP Logger personalizado. Qualquer resposta da API enviada por meio deste método será registrada automaticamente, de acordo com as preferências definidas no registrador. O método é definido e configurado em routes/FlightSetup.php .
É útil quando você deseja a funcionalidade de registro para seus pares de solicitação/resposta sem usar o middleware Flight para interceptar.
Flight::output() leva dois parâmetros: os dados reais a serem enviados ( requerido ) e o código de resposta ( opcional , 200 por padrão).
Flight::output(['sample_message' => 'Amostra de resposta.'], 301);
Flight::validate() Flight::validate() usa análises Swagger-PHP para determinar se um corpo de solicitação passado é válido (contendo todos os atributos necessários) de acordo com a especificação do modelo OpenAPI esperado.
Todos os modelos são declarados como classes e seus atributos são definidos como públicos. Os modelos são definidos em app/models e seguem esta estrutura:
/** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="Atributo de amostra do corpo da solicitação.", * example="String de amostra." * obrigatório=true * ) * @ var string */public $sample_attribute;
} Neste exemplo concreto, description é usada para fornecer uma breve visão geral da propriedade do modelo, required determina se a propriedade é obrigatória ou não e example atribui a ela um valor padrão. Para obter mais informações sobre esquemas de modelo, consulte a documentação do Swagger-PHP.
A classe validadora do modelo é declarada e definida em utils/Validator.php e incluída como um método Flight mapeado personalizado em routes/FlightSetup.php . São necessários dois parâmetros: a classe na qual o corpo da solicitação será validado e o próprio corpo da solicitação.
Flight::validate(SampleModel::class, Flight::request()->data->getData());
O método deve ser chamado dentro de uma rota de API, antes de qualquer método adicional ser chamado. Se o modelo for válido, a solicitação continuará em execução. Caso o modelo não seja validado, ele gerará um código de resposta 400 Bad Request , encerrando a solicitação.
Nota : Flight::validate() depende de Flight::output() , portanto, se você planeja remover o método de saída personalizado do projeto, você deve reescrever o método mapeado do validador conforme necessário.
O projeto vem incluso o PHPUnit, um framework de testes para PHP que, além de se testar, também permite a geração de cobertura de código.
Toda configuração relacionada aos testes com PHPUnit está localizada em phpunit.xml . Existem várias opções disponíveis para configuração:
A localização dos arquivos de teste Dentro da tag testsuites , pode ser definido o local onde os testes serão verificados. Por padrão, isso é tests/unit . Quando um diretório de teste é definido (via tag directory ), os arquivos de teste serão executados em ordem alfabética durante a execução do teste. Se necessário, também podemos definir os arquivos de teste em uma ordem personalizada por meio da tag file .
<conjuntos de testes>
<testsuite name="sample-test-suite">
<directory suffix="Test.php">tests/src/</directory><!-- Por padrão, os arquivos de teste serão executados em ordem alfabética. Se você deseja definir uma ordem específica de execução, defina arquivos de teste individuais--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</testsuites> Tipos de relatórios de cobertura de teste Diferentes tipos de relatórios de teste podem ser gerados após a execução dos testes. Os tipos de log são definidos na tag logging . Todos os arquivos de teste compilados estão, por padrão, localizados dentro tests/build .
<logging><!-- Tipos de logs de teste --><log type="testdox-html" target="tests/build/testdox.html"/>
<log type="tap" target="tests/build/report.tap"/>
<log type="junit" target="tests/build/report.junit.xml"/>
<log type="coverage-html" target="tests/build/coverage"/>
<log type="coverage-text" target="tests/build/coverage.txt"/>
<log type="coverage-clover" target="tests/build/logs/clover.xml"/>
</logging> Arquivos a serem incluídos/excluídos da cobertura de código Você também pode escolher quais arquivos serão incluídos (ou excluídos) do relatório de cobertura de código. Isso é feito através da tag filter , dentro da tag whitelist . Por padrão, a configuração do PHPUnit do projeto cobre arquivos dentro do diretório app , excluindo models e routes (já que essas pastas não contêm código que possa ser efetivamente testado para cobertura de código). Você também pode definir suas pastas e arquivos personalizados de inclusão/exclusão.
<filtro>
<whitelist><!-- O nome da pasta a ser usada para cobertura de código --><directory suffix=".php">app/</directory>
<exclude><!-- Arquivos/pastas excluídos da cobertura de código (arquivos PHP sem métodos testáveis). Edite de acordo com as necessidades do seu projeto. --><sufixo de diretório=".php">app/models</directory>
<directory suffix=".php">app/routes</directory>
</excluir>
</lista branca>
</filtro> Todos os testes unitários devem ser, por padrão, escritos dentro do diretório tests/unit . Os nomes dos arquivos de teste devem terminar com Test.php , para que possam ser descobertos pelo PHPUnit (conforme definido em phpunit.xml ), por exemplo, SampleTest.php .
Uma classe de teste é definida como uma extensão da classe TestCase e pode incluir vários métodos de teste. Ao nomear os testes, você pode usar a seguinte convenção: test + descrição do teste em camel case (por exemplo, testThisIsASampleTest ). Isso permitirá que o nome do caso de teste seja convertido em uma frase descritiva durante a execução do teste, proporcionando uma visão geral adicional ao desenvolvedor sobre o que o teste deve fazer.
/* testes/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest estende TestCase {função pública testThisIsASampleTest() {$this->assertTrue(true);
}
} Para executar todos os testes, execute vendor/bin/phpunit --testdox dentro do diretório raiz do projeto.
root@ubuntu:/caminho/para/projeto$ fornecedor/bin/phpunit --testdox PHPUnit 7.5.16 por Sebastian Bergmann e colaboradores. Amostra Este é um teste de amostra
Para executar apenas um único arquivo de teste, forneça seu caminho: vendor/bin/phpunit --testdox tests/unit/SampleTest.php
A flag --testdox é opcional, mas recomendada, pois irá gerar frases descritivas sobre os testes com base em seus nomes (conforme discutido na seção acima), facilitando o entendimento do que está acontecendo dentro dos testes.
Após a execução dos testes, o relatório de cobertura de código é gerado dentro do diretório tests/build/coverage , e pode ser visualizado abrindo este caminho através de um navegador.
Aldin Kovačević , trabalho inicial no esqueleto e documentação - Aldin-SXR
O esqueleto está licenciado sob a licença do MIT. Consulte o arquivo LICENSE para obter detalhes.
Trabalho em andamento.
