Swagger: Como gerar uma documentação interativa para API REST

7658037Fazer uma boa documentação de uma API REST é fundamental para que desenvolvedores, testadores e principalmente para o usuário final tenham um entendimento claro do comportamento oferecido pelo serviço.

Mas como fazer uma documentação que seja de fácil acesso, possua estruturas claras, interativa e que permita fazer simulações? Fácil, basta usar o Swagger.

O Swagger é uma ferramenta que permite criar documentação para APIs de 3 formas:

  • Manualmente: Permite escrever manualmente a especificação dos serviços e publicá-los no seu próprio servidor ou em algum outro.
  • Automaticamente: Permite que ao mesmo tempo que é criado a API também seja gerado a documentação.
  • Codegen: É um aplicativo que converte as anotações do próprio Swagger contidas no código fonte das APIs REST em documentação.

Neste post vou descrever de forma geral como criar a documentação de uma API manualmente utilizando o Swagger Editor.

O Swagger Editor permite que a documentação da API seja escrita manualmente e como a estrutura que o editor utiliza é muito similar ao formato JSON faz com que o usuário não encontre muitas dificuldades para descrever os seus serviços.

Uma das vantagens do Swagger Editor é que ele possui um conjunto de templates de documentos que podem ser utilizados como base para quem não quer começar uma documentação do “zero”.

Abaixo explicarei um pouco sobre a estrutura do Swagger seguindo um dos templates que a ferramenta oferece e depois como tornamos acessível o documento criado.

Primeiro acesse o Swagger Editor. Vamos utilizar um template como base, para isso clique em “File > Open Example” e selecione o template “petstore_simple.yaml”.

open_example

Figura 1 – Selecione um arquivo de exemplo

Feito isso é possível ver do lado esquerdo da ferramenta o “código” da documentação. A estrutura do template que o Swagger utiliza é muito similar a uma estrutura JSON. Já do lado direito é possível ver o resultado gerado a partir das informações contidas no lado esquerdo da ferramenta. Este resultado nada mais é que a documentação da API construída de uma forma estruturada e amigável para o usuário.

Do lado esquerdo basta editar as informações com o conteúdo do serviço que deseja documentar.

É possível ir conferindo o resultado simultaneamente no quadro a direita conforme são inseridas as informações da API.

Conforme exibido nas imagens abaixo, os templates são bem completos para criar uma documentação:

inicio

Figura 2 – Estrutura inicial

Nesta primeira seção pode-se informar além do nome e descrição da API, também o host onde o serviço está hospedado, o base path e qual o tipo de entrada (consumes) e saída (produces).

Depois da estrutura inicial basta ir detalhando os métodos que a API oferece.

Na próxima imagem conseguimos ver que é possível definir toda a estrutura do método GET do serviço que estamos utilizando como exemplo. É definido uma descrição, os parâmetros do request e parâmetros do response.

get

Figura 3 – Descrevendo o método GET

Na imagem a seguir é possível ver quais são os campos necessários para descrever o método POST, como por exemplo, o nome, tipo e descrição dos parâmetros. A estrutura é similar à anterior.

post

Figura 4 – Descrevendo o método POST

Outro método que temos no template de exemplo e que pode ser usado como guia para documentar um serviço, é o método DELETE. A descrição do método é feita de forma bem simples, basta informar uma descrição, o nome do parâmetro que será enviado no path e no response é determinado qual o código que deve ser retornado quando o método for executado com sucesso.

delete

Figura 5 – Descrevendo o método DELETE

Depois de definido os métodos do serviço, o Swagger também permite que sejam descritos as entidades utilizadas na API. Na imagem abaixo é possível vermos como esta descrição é feita de forma simples. Note que nos métodos anteriores existe o atributo “$ref”, ele indica qual é a entidade que deve ser retornada no response do método.

models

Figura 6 – Descrevendo as entidades da API

Fim! Em poucas etapas um serviço completo foi descrito. Os templates são bem intuitivos e ajudam na construção de uma nova documentação.

Uma vez que a documentação esteja pronta no Swagger Editor, como faço para disponibilizá-la para que outras pessoas possam acessá-la? Fácil, basta seguir os seguintes passos:

1) Faça download do arquivo “swagger.yaml”, que é o nome dado para a documentação que acabamos de descrever acima. Para isso no Swagger Editor clique em “File > Download YAML”.

Para disponibilizar esta documentação em um formato amigável precisamos utilizar outra ferramenta do Swagger, o Swagger UI.

2) Faça o download do arquivo “swagger-ui-master.zip” através do link Swagger UI.

3) Descompacte o arquivo .zip do passo anterior.

4) Copiei apenas a pasta “dist” para o diretório do servidor de aplicação que será utilizado para disponibilizar a documentação. Vou adotar o Tomcat como exemplo, portanto copie a pasta “dist” para o diretório “webapps”.

5) Dentro do diretório “dist” copie o arquivo “swagger.yaml” que foi feito download no passo 1.

6) No mesmo diretório também há o arquivo “index.html”, dentro deste arquivo deve ficar a chamada para o arquivo “swagger.yaml” para que ele seja exibido em um formato HTML.

Para isso é necessário algumas configurações:

  • No arquivo “index.html”, onde estiver o conteúdo “http://petstore.swagger.io/v2/swagger.json” troque por “http://localhost:8080/dist/swagger.yaml”
  • Se o serviço possuir uma chave de acesso, é possível configurá-la também no arquivo “index.html” na função “addApiKeyAuthorization”.

7) Após as alterações realizadas no arquivo, basta salvá-lo.

No arquivo “index.html” na parte dos scripts o conteúdo deve ficar deve ficar simular ao código abaixo:

  <script type="text/javascript">
    $(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://localhost:8080/dist/swagger.yaml";
      }

      // Pre load translate...
      if(window.SwaggerTranslator) {
        window.SwaggerTranslator.translate();
      }
      window.swaggerUi = new SwaggerUi({
        url: url,
        dom_id: "swagger-ui-container",
        supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
        onComplete: function(swaggerApi, swaggerUi){
          if(typeof initOAuth == "function") {
            initOAuth({
              clientId: "your-client-id",
              clientSecret: "your-client-secret-if-required",
              realm: "your-realms",
              appName: "your-app-name",
              scopeSeparator: ",",
              additionalQueryStringParams: {}
            });
          }

          if(window.SwaggerTranslator) {
            window.SwaggerTranslator.translate();
          }

          addApiKeyAuthorization();
        },
        onFailure: function(data) {
          log("Unable to Load SwaggerUI");
        },
        docExpansion: "none",
        jsonEditor: false,
        apisSorter: "alpha",
        defaultModelRendering: 'schema',
        showRequestHeaders: false
      });

      function addApiKeyAuthorization(){
        var key = encodeURIComponent($('#input_apiKey')[0].value);
        if(key && key.trim() != "") {
            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
            window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
            log("added key " + key);
        }
      }

      $('#input_apiKey').change(addApiKeyAuthorization);

      // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
      
      /*  var apiKey = "myApiKeyXXXX123456789";
        $('#input_apiKey').val(apiKey);
      */

      window.swaggerUi.load();

      function log() {
        if ('console' in window) {
          console.log.apply(console, arguments);
        }
      }
  });
  </script>
Listagem 1 – Código da página HTML que irá exibir a documentação criada

Depois de realizado as alterações acima basta inicializar o serviço, no exemplo como utilizei o Tomcat basta executar o arquivo “catalina.bat”.

Para verificar a documentação da API, acesse pelo navegador o endereço abaixo: http://localhost:8080/dist/index.html

swagger

Figura 7 – Página com as informações da API gerada pelo Swagger

Difícil? Não 🙂 . Com poucos passos conseguimos construir uma documentação que possui todos os métodos e detalhes de um serviço, podendo ser vistos de uma forma simples e interativa utilizando as ferramentas do Swagger.

Por MONISE COSTA

Formada em Sistemas de Informação pela PUC Campinas, MATERANA desde 2011. Apaixonada pela área de TI, Analista de Requisitos na maior parte do tempo e desenvolvedora Java/Android por lazer.

Postado em: 24 de fevereiro de 2016

Confira outros artigos do nosso blog

[Webinar] Profile de aplicações Java com Oracle Mission Control e Flight Recorder

24 de julho de 2017

Danival Calegari

Criando Mocks de serviços REST com SoapUI

27 de junho de 2017

Monise Costa

Three laws that enable agile software development

09 de março de 2017

Celso Gonçalves Junior

Medindo performance de uma API REST

21 de fevereiro de 2017

Monise Costa

Deixe seu comentário