O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

PHPRio - Documentar sua api rest com swagger

242 visualizações

Publicada em

O objetivo dessa palestra é mostrar como desenvolver a sua API REST e documentá-la durante o seu desenvolvimento com uma ferramenta chamada Swagger. Além disso sua API estará pronta para testes unitários e funcionais.

Publicada em: Software
  • Seja o primeiro a comentar

PHPRio - Documentar sua api rest com swagger

  1. 1. /** * Documentando sua API Rest * com Swagger * * @author João Gilberto Magalhães */ public function startPresentation() { }
  2. 2. Documentar Sistemas
  3. 3. Documentar Sistemas Sempre que pensamos em documentar vem à nossa cabeça problemas: ● Dá muito trabalho documentar sistemas ● Mesmo que eu documente TUDO sempre estará desatualizado ● Ninguém NUNCA vai ler a documentação Entretanto documentar o sistema, quando bem feito, pode ser muito útil para todos os envolvidos. A seguir algumas regras que devemos utilizar para documentar sistemas.
  4. 4. Documentar Sistemas - Para quem? É importante definir quem será o público alvo da documentação que estamos desenvolvendo. ● Se estamos escrevendo um código temos que documentar para outros desenvolvedores → Annotations PHPDoc; ● Se estamos em uma fábrica de software, a documentação também passa a ser a especificação do desenvolvimento e toda interação relativa à especificação; ● O usuário final, com poucas exceções, requer uma documentação detalhada do Software.
  5. 5. Documentar Sistemas - Quando? Devemos documentar o sistema SEMPRE durante o desenvolvimento. Nunca antes, pois podemos incorrer em erros, Nunca Depois pois se tornará um trabalho gigantesco! ● Estamos com a mão na massa e as ideias estão frescas.
  6. 6. Documentar Sistemas - O que? A documentação tem que fazer sentido e não pode ser "trabalhosa": ● Documentar a chamada do método e a classe com PHPDocs ● Sempre declarar o tipo das variáveis com /** @var */ ● Faça um README.md ensinando como rodar a sua aplicação :) ● Sempre explicar o POR QUE ou PARA QUE de blocos de código e nunca "traduzir" o que está no código.
  7. 7. Documentar Sistemas - O que? O que não deve ser feito: function fibonacci( $n ){ $raizQuadradaCinco = sqrt( 5 ); //pegamos a raiz de 5 $fnParte1 = 1/$raizQuadradaCinco; //1 dividido pela raiz de 5 $fnParte2 = pow((1+$raizQuadradaCinco)/2,$n); // (1 mais raiz de 5) dividido por 2, elevado a n $fnParte3 = pow((1-$raizQuadradaCinco)/2,$n); // (1 menos raiz de 5) dividido por 2, elevado a n $Fn = ($fnParte1) * ($fnParte2 - $fnParte3); //F(n) = ($fnParte1) * {$fnParte2 - $fnParte3} return $Fn; }
  8. 8. Documentar Sistemas - O que? /** * Classe para armazenar o saldo da carteira do cliente * através das suas movimentações */ class Wallet { /** * Adiciona uma movimentação à carteira * @param float $valor */ function addStatement($valor)
  9. 9. Documentação em Micro Serviços Muitas empresas estão adotando a metodologia de micro serviços para desenvolvimento de sistemas. Isso significa que outros times que nem sabem como funcionam o seu código irão consumir a sua API Gasta-se muito tempo com o entendimento dos métodos e nem sempre o que está documentado está atualizado Resultado → Perdemos tempo.
  10. 10. Swagger Swagger é uma das ferramentas mais populares para documentação de API e ferramentas baseadas na especificação OpenAPI Specification (OAS) → https://www.openapis.org/ Formato JSON
  11. 11. Swagger e o PHP Por ser formato aberto JSON não está vinculado especificamente a uma linguagem. De fato, a especificação não pressupõe vinculo com linguagens de programação. Entretanto existe uma ferramenta "zircote/swagger-php" que permite vincular PHP Annotations com definições reconhecidas pelo Swagger. https://github.com/zircote/swagger-php
  12. 12. Vamos praticar?
  13. 13. Instalar o Swagger-PHP O Swagger PHP é uma ferramenta em linha de comando que permite analisar o seu código PHP e então gerar o arquivo JSON. Basicamente: composer require zircote/swagger-php E depois usar ./vendor/bin/swagger para compilar o código.
  14. 14. Aprendendo o Swagger Além do próprio site http://swagger.io/ tem um exemplo da Pet Store (http://petstore.swagger.io/) que mostra as funcionalidades mais básicas. O próprio projeto PHP Swagger tem um exemplo de como documentar com as Anotações baseada no projeto Pet Store.
  15. 15. Colocando as anotações no seu código As anotações do Swagger no PHP começam com prefixo "@SWG". São várias mas está muito bem documentado no projeto do Swagger. /** * Gets an Person Name by Id. * * @SWGGet( * path="/person/{id}", * operationId="get", * tags={"rest"}, * @SWGParameter( * name="id", * in="path", * description="The object Id", * required=true, * type="string" * ) *) /** * Classe contendo os nomes de usuário * * @SWGDefinition(required={"name"}, type="object", @SWGXml(name="Name")) */ class Name { /** * @SWGProperty() * @var integer */ protected $id; }
  16. 16. Guia para criação Como dica, procuraremos sempre documentar: ● Classe ou arquivo que define as rotas deve ter as informações de cabeçalho do Swagger (@SWGInfo) ● Documentar MODELs (@SWGDefinition e @SWGProperty) ● Documentar API (@SWGGet, @SWGPost, @SWGPut, …) (Ver exemplo no código fonte)
  17. 17. Expor a Documentação Online Projeto: https://github.com/swagger-api/swagger-ui Basta copiar a pasta "dist" e colocar o seu swagger.json dentro e vc terá a documentação funcionando. Seus desenvolvedores poderão consultar a API e testar e obter os dados corretamente.
  18. 18. Exemplo
  19. 19. Exemplo
  20. 20. Exemplo
  21. 21. Usar o Swagger para validar Testes Funcionais Projeto: https://github.com/byjg/php-swagger-test Instalar: composer require "byjg/swagger-test=1.0.*" O projeto disponibiliza uma classe "SwaggerTestCase" que analisa o arquivo "swagger.json" e possibilita criar requisições reais e analisar se os parametros de entrada e de retorno estão conforme a especificação.
  22. 22. Testes Funcionais - Exemplo class MyTestCase extends SwaggerTestCase { protected $filePath = __DIR__ . '/../web/docs/swagger.json'; public function testPost() { $this->makeRequest( $httpMethod, // The method $restPath, // The path defined in the swagger.json $statusCode, // The expected status code $queryParam, // The parameters 'in path' (array) $requestBody // The request body ); } }
  23. 23. Validar os parâmetros de entrada em Real Time Também é possível utilizar o "swagger.json" para garantir em tempo de execução que os parâmetros recebidos estão corretos. <?php $swaggerSchema = new SwaggerSchema($contentsOfSwaggerJson); $bodyRequestDef = $swaggerSchema->getRequestParameters($path, $method); $bodyRequestDef->match($requestBody);
  24. 24. Resumindo…
  25. 25. Documentar sua chamada REST: ● Melhora a produtividade das equipes que irão consumir o serviço ● Reduz as demandas de consulta de como utilizar a API ● Com os testes funcionais e de unidade evita que a documentação fique desatualizada em relação ao código; ● É possível utilizar a própria documentação para validar os parâmetros de entrada e reduzir com isso tempo de codificação.
  26. 26. Documentando serviço REST com o Swgger Download do material e exemplos: https://joind.in/talk/6c32f Joao Gilberto Magalhães http://github.com/byjg http://medium.com/byjg Código Exemplo http://bit.ly/2wNDSNY

×