Alura > Cursos de Programação > Cursos de Computação > Conteúdos de Computação > Primeiras aulas do curso Swagger: documentando suas APIs

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 51 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:

Aprenda Computação acessando integralmente esse e outros cursos, comece hoje!

Plus

De
R$ 1.800
por
12X
R$109
à vista R$1.308
  • Acesso a TODOS os cursos por 1 ano

    Formações com mais de 1500 cursos atualizados e novos lançamentos semanais, em Programação, Inteligência Artificial, Front-end, UX & Design, Data Science, Mobile, DevOps e Inovação & Gestão.

  • Certificado

    A cada curso ou formação concluído, um novo certificado para turbinar seu currículo e LinkedIn.

  • Mentorias com especialistas

    No Discord, você tem acesso a eventos exclusivos, grupos de estudos e mentorias com especialistas de diferentes áreas.

  • Comunidade exclusiva

    Faça parte da maior comunidade Dev do país e crie conexões com mais de 120 mil pessoas no Discord.

  • Acesso ao conteúdo das Imersões

    Acesso ilimitado ao catálogo de Imersões da Alura para praticar conhecimentos em diferentes áreas.

  • App Android e iOS para estudar onde quiser

    Explore um universo de possibilidades na palma da sua mão. Baixe as aulas para assistir offline, onde e quando quiser.

Matricule-se

Pro

De
R$ 2.400
por
12X
R$149
à vista R$1.788
  • Acesso a TODOS os cursos por 1 ano

    Formações com mais de 1500 cursos atualizados e novos lançamentos semanais, em Programação, Inteligência Artificial, Front-end, UX & Design, Data Science, Mobile, DevOps e Inovação & Gestão.

  • Certificado

    A cada curso ou formação concluído, um novo certificado para turbinar seu currículo e LinkedIn.

  • Mentorias com especialistas

    No Discord, você tem acesso a eventos exclusivos, grupos de estudos e mentorias com especialistas de diferentes áreas.

  • Comunidade exclusiva

    Faça parte da maior comunidade Dev do país e crie conexões com mais de 120 mil pessoas no Discord.

  • Acesso ao conteúdo das Imersões

    Acesso ilimitado ao catálogo de Imersões da Alura para praticar conhecimentos em diferentes áreas.

  • App Android e iOS para estudar onde quiser

    Explore um universo de possibilidades na palma da sua mão. Baixe as aulas para assistir offline, onde e quando quiser.

  • Luri, a inteligência artificial da Alura

    Luri é nossa inteligência artificial que tira dúvidas, dá exemplos práticos, corrige exercícios e ajuda a mergulhar ainda mais durante as aulas. Você pode conversar com a Luri até 100 mensagens por semana.

  • Alura Língua - Inglês e Espanhol

    Aprenda um novo idioma e expanda seus horizontes profissionais. Cursos de Inglês, Espanhol e Inglês para Devs, 100% focado em tecnologia.

Matricule-se

Ultra

12X
R$209
à vista R$2.508
  • Acesso a TODOS os cursos por 1 ano

    Formações com mais de 1500 cursos atualizados e novos lançamentos semanais, em Programação, Inteligência Artificial, Front-end, UX & Design, Data Science, Mobile, DevOps e Inovação & Gestão.

  • Certificado

    A cada curso ou formação concluído, um novo certificado para turbinar seu currículo e LinkedIn.

  • Mentorias com especialistas

    No Discord, você tem acesso a eventos exclusivos, grupos de estudos e mentorias com especialistas de diferentes áreas.

  • Comunidade exclusiva

    Faça parte da maior comunidade Dev do país e crie conexões com mais de 120 mil pessoas no Discord.

  • Acesso ao conteúdo das Imersões

    Acesso ilimitado ao catálogo de Imersões da Alura para praticar conhecimentos em diferentes áreas.

  • App Android e iOS para estudar onde quiser

    Explore um universo de possibilidades na palma da sua mão. Baixe as aulas para assistir offline, onde e quando quiser.

  • Luri, com mensagens ILIMITADAS

    Mensagens ilimitadas para estudar com a Luri, a IA da Alura, disponível 24hs para tirar suas dúvidas, dar exemplos práticos, corrigir exercícios e impulsionar seus estudos.

  • Luri Vision, a IA que enxerga suas dúvidas

    Envie imagens para a Luri e ela te ajuda a solucionar problemas, identificar erros, esclarecer gráficos, analisar design e muito mais.

  • Alura Língua - Inglês e Espanhol

    Aprenda um novo idioma e expanda seus horizontes profissionais. Cursos de Inglês, Espanhol e Inglês para Devs, 100% focado em tecnologia.

  • 6 Ebooks da Casa do Código

    Escolha os ebooks da Casa do Código, a editora da Alura, que apoiarão a sua jornada de aprendizado para sempre.

Matricule-se
Conheça os Planos para Empresas

Acesso completo
durante 1 ano

Estude 24h/dia
onde e quando quiser

Novos cursos
todas as semanas