Documentando sua API - Swagger

Sabemos que uma API é necessária para expormos vários negócios ou serviços na web. Sendo assim, independente de qual seja o objetivo, APIs existem para que outras pessoas ou sistemas possam usar seus recursos de forma simples e segura.

Entretanto, para que sua API seja bem interpretada e reconhecida pelos demais desenvolvedores, sua documentação é essencial. Assim, uma API bem documentada melhora a experiência do usuário e evita constantes melhorias ou manutenções, pois quem irá utilizar terá total consciência do papel desta API.

Fazer uma boa documentação de uma API é fundamental para que testadores, desenvolvedores e essencialmente o usuário final tenham o entendimento exato do comportamento disponibilizado pelo serviço.

Um fator importante para um programador que irá desenvolver uma API, é que ele tenha compreensão que ela será utilizada por outros desenvolvedores, que possuem outros pensamentos e lógicas, visão de negócio e produto, conhecimento técnico superior ou inferior, pode estar do seu lado ou até do outro lado do mundo, sendo assim, a melhor forma de disponibilizar uma API para que qualquer desenvolvedor possa entende-la e utiliza-la da maneira correta é através de uma boa documentação.

Documentar uma API é mais que oferecer uma página em HTML relatando o que cada método realiza, seus possíveis retornos, sua maneira de autenticar. Documentar é fornecer uma experiência visual e interativa de modo que além de explicar tudo sobre a funcionalidade ela possa ser testada na própria documentação.

Como criar uma documentação que possua estruturas claras e padronizadas, interativa e que permita fazer simulações?

Para ajudar no desenvolvimento, existem várias ferramentas que ajudam a criar uma doa documentação intuitiva. Dentre elas existem 3 especificações principais:

• API Blueprint, mantida pela Apiary, tem uma página bonita e intuitivo onde é fácil encontrar o projeto de interesse e sua documentação.

• RAML, padrão aberto suportado por um grupo de desenvolvedores. É o mais intuitivo para começar a escrever a documentação.

• Swagger, especificação que é assunto deste tutorial, liderada pela Smartbear, tem a maior e mais ativa comunidade de desenvolvedores, parte disso em função de ser a mais antiga no mercado.

O Swagger

Especificação criada em 2011 pela Wordnik (dicionário de inglês online) com objetivo de documentar internamente suas APIs, porém do decorrer de sua evolução, mostrou-se eficaz por atender simultaneamente, necessidade de documentação do cliente e o servidor.

Desenvolvida com base no próprio JSON (porém suporta XML), o formato mais popular para APIs no estilo RESTful, o que traz uma agradável familiaridade à documentação. Além disso, o Swagger é um framework completo para descrição, consumo e visualização de serviços rest.

Seu objetivo é permitir que a documentação evolua na mesma cadência de evolução da API, por ser gerada automaticamente com base nas anotações do código.

Neste framework, existe também um módulo UI permitindo que os desenvolvedores interajam com as APIs em sandbox de forma simples e intuitiva, sem exigir conhecimento de como foi implementada ou mesmo dos parâmetros (que são explicitas na interface).

Atualmente existem 3 formas de implementar a especificação Swagger para documentação das APIs:

• Manualmente: Permitindo escrever manualmente a especificação dos serviços e publicá-los no seu próprio servidor ou em algum outro.

• Automaticamente: Permitindo que ao mesmo tempo que é criado a API também seja gerado sua documentação.

• Codegen: É um Framework interno que converte as anotações do próprio Swagger contidas no código fonte das APIs REST em documentação.

Mas, o que exatamente é este tal de Swagger?

O Swagger é um projeto da especificação OpenAPI, uma linguagem de descrição de contrários APIs Rest. A OpenAPI estabelece um formato JSON com campos convencionais (através de um JSON Schema) para descrever recursos, modelos de dados, URIs, Content-Types, métodos HTTP aceitos e códigos de resposta.

O Swagger é um projeto composto por algumas ferramentas que auxiliam o desenvolvedor de APIs REST em algumas tarefas como:

• Modelagem da API.

• Geração de documentação da API.

• Geração de códigos do Cliente e do Servidor, com suporte a várias linguagens de programação.

Então, vamos praticar um pouco!

Incluindo dependência do Swagger no nosso projeto:

Adicione a dependência Maven ao arquivo pom.xml:

Pronto! Podemos já consultar nossa documentação em:

http://localhost:8080/swagger-ui.html

Para alterar o cabeçalho da nossa documentação, altere o arquivo referente ao @SpringBootApplication, para:

Caso seja necessário alterar o caminho de acesso do Swagger, podemos fazer a configuração via application.properties:

Caso seja necessário ordenar por tipo de métodos a sua documentação:

Para mais configurações específicas ao Swagger, consulte no manual:

https://www.baeldung.com/spring-rest-openapi-documentation