Swagger: documentando suas APIs

Conhecendo a ferramenta - Apresentação

Boas-vindas a mais um curso na Alura, Swagger: Documentando suas APIs. Eu sou o Vinícius Dias e vou guiar vocês nesse treinamento de Swagger. Começaremos entendendo o que é Swagger e como ele pode nos ajudar a desenvolver uma documentação de API, ou até a modelar uma API que não existe ainda. Para isso, não utilizaremos nada de código, nenhuma linguagem de programação.

Eu precisaria escolher uma, e com certeza eu não escolheria a sua linguagem favorita, que não é a mesma de outro aluno, diferente de outro aluno. Então, isso poderia trazer problemas. Sendo assim, vou utilizar uma API falsa, uma API criada somente para esse treinamento através do "mockiapi.io".

A partir dessa API a vamos criar uma documentação, para criar documentação iremos começar a conhecer as ferramentas dos Swagger, dentre elas o SwaggerEditor. Então, dentro do "editor.swagger.io", começaremos a entender como definir informações sobre API, licença, detalhes de contato, documentações externas, etc. E a partir disso, nós vamos definir os endpoints. Cada endpoint vai ter mais de um verbo, vai ter um verbo ou mais HTTP.

[01:12 ] Dentro disso mapearemos as possíveis respostas, parâmetros, se existirem, o corpo de uma requisição, enfim, conseguiremos definir muitos detalhes sobre cada um desses endpoints. Além disso, organizaremos um pouco a configuração do API, separando pedaços de código em componentes.

Então teremos esquemas separados, e falando em componentes, falaremos também um pouco sobre a autenticação. Como ter esquemas de segurança, com exemplo, definir como utilizar a autenticação HTTP, utilizando o JWT por exemplo. No final, iremos ver como ter isso tudo em uma infraestrutura própria, nossa.

Porque inicialmente não vamos precisar instalar nada, tudo estará no servidor do Swagger, mas depois eu quero trazer isso para a minha máquina, até para poder disponibilizar, através de algum servidor, para possíveis clientes.

Então teremos o Swagger - UI configurado na nossa máquina, exibindo toda aquela documentação, e uma documentação viva, onde eu posso realmente realizar requisições. Ou seja, além de ajudar a equipe de desenvolvimento, isso pode ser uma baita ferramenta para equipe de produto e para que pedir vendas, para mostrar como nossa API funciona e etc.

Espero que você tire bastante proveito e se ficar com alguma dúvida, não existe, você pode abrir uma questão lá no fórum. Eu tento responder pessoalmente sempre que possível, mas quando eu não consigo, temos uma vasta comunidade de alunos, moderadores e instrutores que, com certeza, alguém vai poder te ajudar.

Mais uma vez sejam muito bem-vindos, espero que vocês aproveitem bastante. Espero vocês no próximo vídeo, para começarmos a conversar melhor sobre o que é esse tal de Swagger.

Conhecendo a ferramenta - Entendendo o Swagger

Bem-vindos de volta. Antes de começarmos a fazer qualquer coisa, vamos entender o que é Swagger, o que é esse nome, o que esse nome significa e o que ele nos fornece. Vamos lá, quando entramos no site "swagger.io", temos a seguinte chamada "API Development for Everyone".

Então, o que o Swagger faz é simplificar o desenvolvimento de APIs de alguma forma. Ele possui várias formas para fazer isso, para simplificar e para nos ajudar desenvolver e documentar APIs, só que iremos focar nessa parte de documentação. Nós já temos uma APIs desenvolvidas, iremos utilizar uma API de exemplo, mas vamos focar na documentação dessa API que já existe.

[00:48] O Swagger nos fornece algumas ferramentas, um editor de documentação, uma visualização dessa documentação, utilizando um formato específico, ele fornece um gerador de código baseado nessa documentação. Vamos dar uma olhada rápida clicando em "Explore Swagger Tools" na página inicial do site, para explorar as ferramentas do Swagger.

Ele nos mostra as três ferramentas open source que ele tem. Ou seja, essas ferramentas são gratuitas e de código aberto. Se eu voltar para página inicial do site e rolar para baixo, podemos ver no centro da página a opção "Open Source Tools", veremos exatamente as mesmas três ferramentas, o "SwaggerEditor, Swagger UI e o Swagger Codegen", codegen de code generator.

Então o Editor ele permite que desenvolvamos, que escrevamos a documentação da API, que façamos o design da nossa API. Ele ajuda na modelagem de uma API, se ainda tivermos pensando em como vai ser, e na documentação caso essa API já exista, iremos usar bastante ele.

Existe o Swagger UI para você fornecer um ambiente visual do que criamos com o Swagger Editor, basicamente. Então imagina que você documentou toda a sua API, está todo modelado, e que você queira fornecer isso como documentação para o cliente que vai utilizar a sua API. Você pode fornecer através do Swagger UI, já vamos ver isso tudo, na prática, estamos apenas entendendo as ferramentas.

Nesse treinamento trabalharemos o tempo todo com o Swagger Editor e vamos dar uma olhada nos Swagger UI. “Vinicius, e o Codegen, por que que não iremos utilizar?” Porque para utilizar ele eu ia precisar escolher alguma linguagem, porque se dermos uma olhada nele, ele pode gerar servidores ou clientes para diversas linguagens, como as "aspnet5, aspnetcore, erlang, PHP, node, phyton,".

Então ele consegue gerar código em muitas linguagens, com muitas tecnologias e eu precisaria escolher uma, ou algumas linguagens para fazer isso, com certeza ia deixar alguma de fora. Por isso, não iremos entrar nessa parte, mas essa parte aqui depende do conhecimento que nós aprenderemos na hora de fazer o design de uma API, ou a documentação de uma API.

Recapitulando, o que é Swagger, para finalizarmos. O Swagger é, basicamente, um conjunto de ferramentas que nos ajuda a fazer o design, ou seja, fazer a modelagem, a documentar e até gerar código para desenvolvimento de APIs. Iremos escrever a documentação? Como fazemos com essa documentação?

Porque temos um meio Editor, então, teoricamente, vamos editar usando algum formato. E é exatamente sobre o formato que iremos utilizar que eu vou conversar com próximo vídeo, mas ainda sem colocar a mão na massa.

Conhecendo a ferramenta - OpenAPI

Bem-vindos de volta, logo começaremos a escrever realmente um arquivo em um formato específico, mas antes de escrevermos, eu quero só pincelar que formato é esse, como que sabemos quais são os valores que pode colocar lá, ou não.

Então o Swagger é uma ferramenta, um conjunto de ferramentas, e ele trabalha em cima de uma especificação, que a "OpenAPI Specification". Então vamos para a página inicial do Swagger, e se rolarmos para baixo temos a "OpenAPI Specification". Existe uma especificação de como você pode modelar APIs, como você pode documentar o design de uma API.

Então essa nos diz que podemos ter informações de uma API, os caminhos ou os end pointsdessa API, e cada end point tem seus verbos. Temos informações de componentes, como os esquemas, componente de segurança, podemos ter tags para organizar, enfim, tem muita coisa nessa especificação.

É utilizando essa especificação que escrevemos a nossa documentação, que escrevemos o documento através do Swagger Editor para o Swagger UI renderizar. Vamos só dar uma olhada na página do "OpenAPI Specification", não vou passar em toda a especificação, porque era gigante. Então seria impossível e seria muito maçante, vamos só dar uma olhada.

Existem duas versões mantidas hoje, a versão "2.0", bastante famosa, e a mais recente, a 3.0, que utilizaremos. Então na página do "OpenAPI Specification" eu vou clicar na opção "3.0", temos uma versão simplificada que p Swagger fornece em seu próprio site. Mas se você acessar a internet e pesquisar a "OpenAPI Specification" você vai ter a especificação oficial, completa.

Mas eu gosto bastante de como o Swagger organizou, com a interface do Swagger. Então sempre que eu precisar acessar a referência de alguma coisa, sempre que eu precisar acessar a documentação da especificação, vou acessar através do site do Swagger. Mas deixarei no "Para saber mais", o site oficial da especificação.

Então a página faz umas introduções, explica que existe um documento que descreve uma API, logo teremos um documento, um arquivo que descreve algo que uma API faz. Seus end points, as suas rotas, os métodos de cada rota, os verbos da rota, enfim, tudo isso iremos conseguir utilizando essa especificação.

Temos que a parte das versões do OpenAPI e conseguimos ver a especificação em si, a estrutura do documento. Então temos tipos de dados, nós temos os esquemas, o que conseguimos informar em cada uma das partes. Por exemplo, na hora de eu passar informações sobre API, eu posso vir aqui nesse Info Object e eu sei que posso ter um título, uma descrição de termos de serviço, contato, etc.

Em cima disso que iremos trabalhar, desses campos que a especificação fornece. Se eu estou falando muito e essas coisas não estão ficando muito claras, então vamos parar um pouco com a teoria e no próximo vídeo vamos ver na prática. Como é esse visual do Swagger Editor, o que é Swagger UI, um pouco mais na prática. Então, vamos ver como essas ferramentas funcionam no próximo vídeo.

Sobre o curso Swagger: documentando suas APIs

O curso Swagger: documentando suas APIs possui 91 minutos de vídeos, em um total de 52 atividades. Gostou? Conheça nossos outros cursos de Computação em Programação, ou leia nossos artigos de Programação.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Conhecendo a ferramenta
• Definindo a API
• Definindo endpoints
• Schemas
• Segurança
• Infra própria