Documentando API com Swagger

Com o intuito de aprender um pouco mais sobre APIs (Application Programming Interface), comecei a ler vários artigos sobre o assunto, bem como,  pesquisar por várias APIs. Percebi que algumas estavam bem documentadas e outras nem tanto, dificultando um pouco o entendimento do comportamento dos recursos. Foi nesse momento que percebi que tão importante quanto desenvolver, é criar uma documentação bem definida, e assim, me deparei com o Swagger, uma ferramenta que particularmente eu achei muito legal, ela permite criar a documentação de forma bem rápida.

Resolvi escrever esse artigo para poder demonstrar de forma bem simples como criar a documentação de uma API. Vou utilizar um exemplo bem simples para que o artigo não se estenda muito.

Então sem mais delongas, vamos para o que interessa. Para criar a documentação utilizaremos o editor online, que pode ser acessado pelo link https://editor.swagger.io/.

Ao acessar o link, podemos perceber que já vem vários exemplos que podem ser seguidos, como mostra a imagem abaixo:

1

Para começar, iremos editar primeiro o cabeçalho, onde especificaremos algumas particularidades da API. Lembrando que a identação é super importante, pois, é assim que o Swagger reconhece as propriedades.

A propriedade “swagger” define a versão da ferramenta, nesse caso, podemos manter a 2.0. Depois colocaremos propriedade “info”, que contém a descrição, a versão (da API), o título e o contato (no caso da imagem abaixo preenchi com meu contato). Em seguida colocaremos a propriedade “host”, que é a url de sua aplicação e o “basePath”. Para finalizar o cabeçalho vamos definir o schemes, que geralmente é o https.

2

 

3

A seguir vamos criar as “definitions”, que vamos fazer no modelo dos objetos de nossa API. Primeiramente colocamos o nome da definition, o tipo dela, os campos requiridos e enfim as propriedades.

Captura de tela de 2017-11-12 23-20-39

Agora vamos criar o recurso e os verbos / ações (GET, POST, DELETE, etc), que no Swagger são denominados como “paths”. Definimos o nome do recurso, que não poderá ser repetido. Depois colocamos o verbo, nesse caso vamos fazer um GET. Na imagem abaixo foi definido tags, sumário, descrição e respostas para o verbo.

Podemos perceber que no caso de resposta “200”, o retorno será um array contendo os itens da “definitions” que criamos anteriormente. Assim, nosso GET já está pronto e ficou conforme imagem abaixo:

Captura de tela de 2017-11-12 23-00-22

Captura de tela de 2017-11-12 23-21-49

Agora vamos fazer o verbo POST, que é muito parecido com a estrutura que fizemos do GET, a única diferença é a propriedade “parameters” (define os parâmetros a serem passados). Como já criamos o recurso, repare que não precisamos criar outro, visto que o verbo POST faz parte do mesmo recurso que o verbo GET.

Captura de tela de 2017-11-12 23-03-53

Os demais verbos seguem a mesma linha de raciocínio, entretanto, como o intuito era apenas mostrar um exemplo bem simples, não será mostrado a implementação, porém, você pode conferir a documentação completa do exemplo aqui mostrado, acessando o link http://www.andcordeiro.com.br/documentation.html.

Por último, podemos criar um arquivo referente a documentação feita, basta ir na opção “Generate Client” e escolher uma das opções disponíveis. Nesse caso escolheremos o html2.

a

Apesar de não ter sido mostrado muitos recursos do Swagger neste post, ele têm muitas outras coisas interessantes que podem ser conferidas na documentação, acessando o link https://swagger.io/specification.

Deixe uma resposta

O seu endereço de email não será publicado Campos obrigatórios são marcados *

Você pode usar estas tags e atributos de HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>