Primeiras aulas do curso Swagger parte 1: Crie uma documentação APIs REST

Swagger parte 1: Crie uma documentação APIs REST

Primeiros passos com Swagger - Introdução

Olá, bem-vindo ao curso de Swagger, o ByteBank é um banco digital e esse banco está criando uma API, uma aplicação mobile, para que os clientes possam consultar a sua movimentação bancária, fazer depósito, débito entre outras coisas para facilitar a vida do cliente.

Nós fomos contratados para desenvolver essa API e a documentação, alguns times estarão envolvidos nesse desenvolvimento, temos o pessoal do Front-End, que é quem vai fazer as telas; o pessoal de Back-End, que vai fazer todo código que rola por de baixo dos panos; pessoal de banco de dados para cuidar de guardar esses dados da melhor forma no banco e o pessoal de qualidade que é quem realmente vai testar a API.

E para que todos esses times desenvolvam uma única coisa e que tenha todas as regras de negócio sem erros, vamos utilizar uma ferramenta chamada swagger, o swagger vai nos auxiliar para criar tanto a documentação quanto a API e vamos ver isso na prática.

Para utilizar o swagger vamos utilizar aqui o navegador acessando o “editor.swagger.io” e vamos criar um script, esse script é muito semelhante ao Json, e ele sempre vai trabalhar com chave e valor, e é com esse jogo de chave e valor que vamos gerar o script e a partir disso gerar aqui do lado direito uma documentação interativa.

Onde seja o cliente que nos solicitou a API ou alguém do time que queira ver o que a API oferece, quais são as operações, como que funciona por exemplo a operação de cadastro de cliente, consulta de conta, extrato entre outras coisas, ele pode ver a parte dessa documentação, como tudo isso funciona.

Nós temos aqui a baixo também, um exemplo de como vão ficar os modelos que são os formatos de dados que vamos trafegar, seja dados do cliente, dados da conta da transação e depois por fim, aqui do lado esquerdo novamente vamos pegar esse script swagger e gerar a nossa API a partir de um clique.

Então vamos vir aqui no generate server, seleciona qual a opção entre as mais de 20 opções que temos para gerar a API, vou até mostrar aqui como exemplo, vamos dar um clique aqui e ele vai fazer o download, olha lá o download desse arquivo, e esse arquivo o que é? É a nossa API prontinha, para depois customizarmos toda essa regra de negócio, mas a estrutura da API em si já estará pronta.

E vamos ver isso também aqui no eclipse, porque depois vamos descompactar essa API, importar aqui para a eclipse, no meu caso aqui eu já tinha baixo e aqui, nós temos toda a estrutura, isso eu vou mostrar para vocês no curso, toda essa estrutura, mas aqui vamos já fazer um teste na API? No Run As aqui? Java Application? Vamos subir a aplicação, repare que ela sobe bem rápido.

E essa daqui eu não fiz nada, foi só a partir daquele zip descompactado e já colocamos ela para rodar e vamos lá no navegador para acessar essa API no endereço “localhost:8085” eu já tenho minha colinha aqui e vou dar um Enter. Olha lá, essa é a API que vamos criar, e nós temos semelhante, vou voltar aqui a aba do swagger editor, aqui essa documentação interativa e aqui nessa nossa nova aba que acessamos a API, também podemos ver essa documentação interativa.

Então quer dizer, além do cliente ter uma API, ele também vai poder acessar toda sua documentação. Agora o que nós podemos ver aqui em resumo do swagger? Ele é um pacote de ferramentas para desenvolvermos a API, e vamos modelar esse script como eu mostrei, vamos gerar essa API, depois documentar tudo isso e por fim testar.

Eu espero vocês no nosso curso, sejam bem-vindos eu sou Carl Edwin e serei um instrutor, muito obrigado e até mais.

Primeiros passos com Swagger - Criando o primeiro endpoint

Vamos por a mão na massa. Primeira coisa que vamos fazer é acessar o swagger editor, então vamos acessar no caminho editor.swagger.io, reparem que já de cara ele mostra para gente um exemplo de swagger, esse exemplo é um exemplo do Petstore, então aqui ele tem do lado esquerdo, um script swagger onde fala de versão, info, várias coisas e aqui do lado direito nós temos a documentação interativa que é gerada a partir desse script.

Agora o que nós vamos fazer? Aqui do lado esquerdo nós vamos gerar o nosso próprio script vamos selecionar tudo aqui com “Ctrl + A” ou “Command + A” e dar um delete, com o editor zerado vamos começar o nosso script, a primeira coisa que vamos fazer é colocar aqui a palavra swagger e vamos dar aqui um dois pontos e espaço.

Ddo lado direito já podemos observar que ele já compilou e já está nos indicando algumas coisas que estão faltando, ele diz “vamos utilizar a versão 2.0 ou a 3.0?”, no nosso caso aqui do lado esquerdo, vamos utilizar a “2.0”, sempre com aspas simples. Agora ele já explode alguns erros aqui para gente, um é falando da info aqui do lado direito e outra é falando do path, que são coisas que vamos resolvendo pouco a pouco.

O swagger ele vai trabalhar da seguinte forma, sempre ele vai trabalhar observando aqui do lado esquerdo com chave e valor, aqui em vermelho nós temos a palavra swagger que vai ser a chave e aqui em verde nós temos o valor que no caso é 2.0. Vamos saltar duas linhas aqui? E agora já vamos fazer o nosso primeiro EndPoint, para fazer um EndPoint já vamos acabar resolvendo um problema.

Que é um problema aqui do paths, o que é o path? São as operações que a nossa API vai oferecer, então digitamos aqui “paths:” Enter para próxima linha e um Tab, então vou dando Tab para incluir uma nova propriedade dessa palavra chave. Para fazer essa primeira operação, vamos fazer primeiro o endereço, nós vamos fazer o cadastro de um cliente então aqui colocamos “/cliente”;.

Agora ele já deu um outro erro aqui se observamos do lado direito, ele está dizendo que a palavra /cliente, não é, e não pode ser um objeto, realmente, ele é só o nosso endereço, então vamos saltar mais uma linha dar um Tab, e agora o que vamos fazer? Vamos indicar qual é o método Rest que vamos utilizar, se vai ser o post, o get ou o put, no nosso caso vai ser o put, sempre que estivermos trabalhando com Rest vamos utilizar o post para fazer o cadastro de qualquer coisa que seja.

Se eu for fazer uma alteração já será outro método, então o nosso editor aqui do swagger ele nos dá a possibilidade também do auto complete, então damos um “Ctrl + Espaço + Enter”, ele já indica algumas propriedades básicas que ele vai utilizar, reparem que do lado direito ele já criou aqui para nós a primeira operação com essa botãozinho verde escrito POST, vamos clicar nele e vamos correr aqui um pouco a tela.

Conseguimos observar que ele tem parameters, responses aqui, esse responses é um código 200, quer dizer que teve sucesso na requisição e nós do lado esquerdo conseguimos ver esse 200 também. Então tudo que eu digito do lado esquerdo ele vai renderizar do lado direito, e se der algum erro também, aqui ele está dando um erro, já vamos ver o que é, vamos clicar aqui do lado direito.

Vamos ver o que ele está dizendo aqui, description tem que ser uma string, vamos já resolver isso então, já tenho aqui o Post, o summary, esse summary vai ser um título resumido que ainda não existe, ele vai ficar aqui do lado direito e já vamos digitá-lo para vermos o que ele vai mostrar, “cadastra cliente”, vamos ver a mágica? Ele já aparece aqui do lado direito.

Agora vamos abrir essa operação para colocarmos a description, “Cadastra o novo cliente”, e vamos ver, ele já mostra do lado direito para nós, agora essa resposta aqui de 200 normalmente ela é utilizada quanto estamos fazendo o método get do Rest, no nosso caso de cadastro já vai ser 201, que é sucesso ao fazer o cadastro e aqui podemos colocar então, código de resposta e uma breve descrição, no nosso caso a breve descrição vai ser “cadastro efetuado com sucesso”.

Agora temos duas outras opções, a primeira é se de repente eu enviar alguma informação lá para o servidor, ele faz alguma validação, o CPF inválido ou alguma coisa do tipo, então vamos devolver um outro código, que vai ser o código 400, então vamos lá saltar uma linha, não vamos ficar aqui no nível de indentação do description, vamos voltar mais um aqui para esquerda, então vamos colocar agora 400, vai ser o código de resposta e saltamos uma linha, damos um Tab, vamos colocar uma description?

Ele já nos ajudando aqui no auto complete novamente, description e colocamos “requisição inválida”. Agora uma última opção aqui que vamos colocar é se dar algum erro que não esperamos no servidor, então vamos colocar um erro aqui com código 500, salta uma linha Tab, novamente description e aqui no caso vai ser um erro interno no servidor.

Porque essa palavra “no” ficou de outra cor? Isso é um pequeno bug no editor, mas não vai influenciar em nada, agora que já temos a operação, para quando formos gerar efetivamente a API, vamos precisar colocar lá, qual vai ser o nome do método e o nome do método dessa operação dentro da aplicação java, ele vem aqui no operation ID, então esse operation ID é o ID da operação e também o nome que vai ter o método do java.

Então podemos colocar aqui “cadastra cliente”, bateu o olho nesse método já vamos saber o que ele faz, outra coisa que também é muito importante analisarmos é o que eu vou estar mandando para o servidor, vai ser um txt? Um xml? Ou um json? No nosso caso vamos estar sempre mandando objetos json para o servidor, então vamos colocar aqui um consumes que vai ser a palavra chave para isso, dou Enter aqui para saltar a linha, Tab - Espaço.

E vamos colocar o tipo de arquivo que vamos mandar, “application/json”, só que quando fizermos o cadastro para esse cliente, vamos querer também que ele nos devolva uma confirmação desse cadastro e as informações desse cliente e como que ele vai nos devolver? Também um json, então agora ele vai produzir um json, então colocamos aqui, “produces:”, pulamos uma linha Tab – Espaço “applicaiton/json”.

Vamos olhar aqui o que nós temos já mudado aqui na nossa operação do lado direito, olha lá, nós já temos renderizado aqui, código 201 para cadastro com sucesso, o 400 e o 500, olha que interessante, essa documentação é uma documentação que qualquer um vai poder olhar e entender de uma forma muito mais clara do que se tivesse olhando esse script.

Por isso esse sucesso do swagger editor para quem está fazendo a parte da API e do swagger UI que é um interface para o usuário que vai facilitar a visualização dessa documentação. Agora tem mais uma coisa que não configuramos ainda, eu quero fazer o cadastro do cliente, mas eu não informei nada sobre o cliente, não coloquei nome, telefone, CPF, não informei nada disso na operação ainda, abrindo aqui não tem nada.

O que nós vamos fazer então? Colocar mais uma palavra chave aqui depois de operation ID, vamos colocar aqui a palavra chave “parameters”, começo a digitar ele já me ajuda e nesse parameters ele vai poder ter várias opções, então saltamos mais uma linha e Tab, e a primeira coisa que vamos falar é, eu vou estar mandando essa informação do usuário, no caso vamos colocar agora só o nome do usuário nesse envio, eu vou colocar essa informação no corpo da requisição.

Que aqui nós vamos utilizar a palavra body, então eu coloco um “- + Espaço”, e digito “In:” o In por quê? Vai no caso dentro da requisição, então “- In: Body”, e aqui já falamos que vai ser no corpo da requisição, salto mais uma linha Tab e aqui eu coloco agora no name, se eu não tivesse com a indentação correta ele não iria fazer esse auto complete.

Então qual vai ser o nome desse parâmetro que eu vou mandar? Vai ser cliente, só que tem um pequeno detalhe aqui que precisamos tomar cuidado, normalmente quando eu coloco o nome do parâmetro igual ao nome do path aqui que digitamos, ele dá um erro. Então o ideal é colocar aqui um underline no final, agora, reparem que na linha 15 aqui ficou tudo branco, quer dizer que está faltando alguma coisa na minha indentação, eu esqueci der dar um Espaço aqui, pronto.

Agora com esse espaço, podemos continuar, a propriedade aqui vai ser a propriedade cliente no body e eu vou criar o objeto json, como eu defino, estou mandando um objeto na requisição? Colocamos a palavra-chave aqui “schema”, e com essa palavra-chave “schema”, vamos definir um tipo para ele, com a palavra “type:” na linha de baixo, e colocamos a object, porque afinal vai ser um objeto que vamos mandar.

Salto mais uma linha, porque esse objeto vai ter algumas propriedades, esse usuário vai ter bastante informação, mas para esse momento vamos colocar apenas o nome, e aqui não vamos chamar de nome, vamos chamar de titular, então vamos colocar aqui, properties e damos um Enter e já saltamos para linha de baixo, então aqui vamos colocar titular, então essa é a primeira propriedade que o nosso objeto vai ter.

Vamos ver como está ficando aqui do lado direito? Eu sei que ele ainda está com erro, deixa eu ver, ele ainda não está mostrando nada para gente, reparem que aqui o objeto está vazio, isso vai mudar, o titular nós vamos colocar o seguinte, o titular vai ter um tipo especifico, que pode ser número, pode ser uma string, vamos saltar mais uma linha aqui, na linha 20 damos um Tab e agora colocamos type que é o tipo dessa propriedade e vamos falar que é uma string.

Agora, só vou até o final aqui para facilitarmos essa visualização, então properties, titular, type, string, ótimo. Então aqui do lado direito ele já está mostrando o meu objeto cliente com o nome da propriedade e o valor padrão dele que é string, mas dá para mudarmos isso? Dá para por exemplo, colocarmos um nome de exemplo, para quando alguém olhar a documentação já ver mais ou menos, como ficaria se fosse real.

Então ele pode colocar aqui um “example” dou um Enter, e escrevemos aqui por exemplo “Janete Silva”, então olha lá, do lado direito a tela já piscou e já mudou, então quando o usuário olhar para essa documentação, “ah titular, aqui pode ser então o nome desse cliente”.

Acredito que sejam essas informações, vamos ver aqui se faltou alguma coisa já definimos swagger, path aqui está certinho, o post, as configurações iniciais, o tipo de envio, os parâmetros. Agora eu falei mais uma coisa, eu falei que nós vamos mandar a informação e depois ter ela de volta, mas onde que eu defini que eu vou retornar os dados do usuário? Em lugar nenhum, onde eu defini que deu sucesso no meu cadastro? Foi aqui no response código 201.

Então é exatamente aqui depois de description, aqui na linha 25 damos um Enter, que vamos colocar o tipo de retorno da nossa operação, vamos aqui do lado direito rapidamente, só ver aqui no código 201, ele tem simplesmente aqui a description e ele vai mostrar depois do que vamos fazer agora, o resultado do retorno dessa resposta, que vai ser um objeto cliente, como que fazemos isso?

Clicamos aqui, voltando do lado esquerdo, vamos copiar na linha 16 até a linha 21, toda essa configuração de cliente e agora vamos vir aqui na 25, copiamos com “Ctrl + C”, agora vamos dar um “Ctrl + V” aqui na linha 26, olha lá, já mudou novamente o meu swagger e aqui a minha documentação.

Então aqui, no código 201 temos um exemplo aqui do retorno, que nesse caso vai ser a Janete e com isso finalizamos essa aula.

Primeiros passos com Swagger - Configurando info

Então vamos continuar de onde nós paramos, nós precisávamos resolver aqui o erro do info, e chegou a hora de resolvermos, então vamos aqui no lado esquerdo na linha 2, vamos dar um Enter aqui, vamos aqui na linha 4 e agora vamos digitar aqui info, aproveitando o auto complete dele damos um Enter.

Nessa seção vamos configurar como se fosse o título da nossa documentação interativa, então vai ser a versão, título, uma breve descrição, entre outras coisas, vamos fazendo juntos e eu vou explicando o que é cada coisa.

Primeira version, que é a versão aqui do projeto aqui na linha 5, colocamos “1.0.0” , agora configuramos o título que é a segunda palavra chave aqui, então podemos colocar um título “ByteBank API”, agora precisamos descrever aqui o que essa API faz, ela faz a administração da movimentação bancaria do correntista e também faz o controle de acesso através da senha e o CPF.

Então vamos lá, “Administra a movimentação bancária do correntista e controla o acesso através de CPF e senha”, pronto. Então já conseguimos aqui do lado direito observar que o título já está sendo exibido, a versão e a descrição. Temos aqui termsOfService, o que é isso? São os termos de uso da nossa API, o que ela oferece e o que ela não oferece, o que podemos fazer, é colocar aqui o endereço da API e no final, colocamos aqui termo de uso, mas tem um detalhe, ainda não configuramos o endereço da API.

Então já podemos fazer isso, vamos aqui a linha dois, e colocamos aqui, primeiro qual vai ser o protocolo de acesso ou os protocolos de acesso, que essa API vai utilizar? Então para isso colocamos aqui “schemes:” e damos um Enter, agora como é mais de uma informação que vamos colocar no valor dessa palavra chave, pulamos uma linha, Tab – Espaço, olha lá, com auto complete ele já mostra para gente os protocolos de acesso disponíveis.

Nós vamos utilizar o Http e o Https, então primeiro “- Http” aqui, e espaço e traço na linha de baixo “- Https”, utilizando o auto complete, certo, então ele já resolveu isso também. Vamos ver aqui do lado direito abaixo aqui já conseguimos ver que os protocolos estão sendo exibidos na documentação, agora precisamos configurar também qual vai ser o nome que vai no endereço dessa API, então voltamos aqui bem no início da linha 8 e colocamos localhost para rodamos o local.

Mas antes do localhost que é o valor, podemos estar colocando host, começo a digitar host ele já me ajuda, dou um Enter aqui e colocamos “localhost: 8085”, porque eu não coloquei 8080? Porque o 8080 pode dar conflito com alguma outra coisa que você já tem instalado na sua máquina.

Agora já vamos configurar na linha de baixo o “basePath:”, esse basePath vai ser efetivamente a segunda parte do nome da nossa API, deste endereço, então colocamos aqui “/” para falar que está dentro do contexto, colocamos “/bytebank –api/v1” e vamos indicar também qual é a versão, então colocamos v1.

Então agora nós já temos aqui do lado direito o basePath, ou seja, o endereço da nossa api, então título e as outras coisas que já configuramos. Agora sim eu consigo colocar, voltando aqui do lado esquerdo na linha 15, qual vai ser o endereço dessa parte aqui que fala dos termos de uso da nossa API, então colocamos aqui “http:”, vou copiar daqui de cima 8085 na linha 8, volto para linha 15, “http://localhost:8085”, isso para não errarmos o endereço.

Agora volto na linha 9, copio o basePath e coloco depois do localhost, então aqui já temos uma parte do endereço da página de termsOfService, agora damos um “/” no final e vamos colocar aqui qual vai ser o nome dessa página “/termo-uso”, já temos aqui esse endereço, agora outra coisa que ele já está reclamando, vamos ver até do lado direito ali em cima, ele está dizendo que na info a parte de contato não pode ser uma string e aqui a url também e o email.

Como que nós vamos resolver isso? Preenchendo, então nós vamos colocar na linha 16 do lado esquerdo, contact, colocamos com quem vamos conversar caso precisemos entrar em contato com o suporte dessa api, então, como pode ser o João, a Maria, o Zeca, não vamos colocar o nome em específico, vamos colocar aqui “Suporte”.

E agora qual vai ser a url a esse suporte caso exista? Então podemos botar aqui na linha 15, copiamos esse endereço aqui dos termos de uso, colamos aqui na linha 18 e o que vamos mudar vai ser só o final, escrevemos aqui “Suporte” que vai ser um outro endereço também da API, onde o usuário vai poder ter acesso às informações de suporte, mas eu também posso enviar um email ao suporte, então colocamos aqui a informação de email.

“suporte@bytebankapi.com”, já resolvemos os erros do info e o legal é que o swagger vai nos ajudando a todo momento recompilando, vocês de repente podem ver a tela piscando, mas isso é normal porque ele está renderizando novamente.

E agora nós temos essa última opção aqui, que é a parte license, tem o name e url, isso aqui normalmente é utilizado para quando você cria um software, ou de repente uma API open source e você vai colocar ali essa parte de licença de cópia ou de repente de alteração essas coisas. Não vai ser o nosso caso, então nós vamos apagar.

Então com isso já finalizamos a configuração do info, mais adiante nós vamos ver a parte de consulta do cliente, muito obrigado e até mais.

Sobre o curso Swagger parte 1: Crie uma documentação APIs REST

O curso Swagger parte 1: Crie uma documentação APIs REST possui 159 minutos de vídeos, em um total de 36 atividades. Gostou? Conheça nossos outros cursos de Java 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 Java acessando integralmente esse e outros cursos, comece hoje!

  • 1112 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

Premium

  • 1112 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$75
à vista R$900
Matricule-se

Premium Plus

  • 1112 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$100
à vista R$1.200
Matricule-se

Max

  • 1112 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$120
à vista R$1.440
Matricule-se
Procurando planos para empresas?
Acesso por 1 ano
Estude 24h/dia onde e quando quiser
Novos cursos toda semana