Implementar o swagger | Swagger: documentando suas APIs

Implementar o swagger

Olá. Depois de concluir o treinamento, ainda ficaram algumas dúvidas.

Entendi que o swagger é para documentar. O que não ficou claro é sobre o verbo POST.

Me explica mais claramente isso por favor. Fazer um post salva a informação no meu banco, certo? Vimos que durante as aulas foi feito um POST e recuperamos a informação com um GET. Se entendi bem, que banco seria este? Suponho que um banco de dados de testes apenas, pois qual a lógica de deixar alguém usar o swagger para salvar um dado em alguma base de dados útil?

Por outra lado entendi que o swagger pode ser usado à parte do código. Até então eu achava que necessariamente deveria estar junto com o projeto. Pois já havia feito treinamentos (não aqui) onde o instrutor simplesmente vai instalando e configurando. Aí achei que deveria ser assim.

E em relação a vários projetos onde tenho vários endpoints? Posso colocar todo os endpoints de todos os vários sistemas diferentes dentro de um arquivo yml? Vimos que podemos usar o docker. Se for documentar os endpoints de vários sistemas diferentes, como faz? Vários containers ou como falei acima?

Oi, Flavio! Tudo bem?

Desculpa a demora por um retorno.

Utilizamos o verbo POST no Swagger para enviar dados para o servidor, sendo possível salvar informações no banco de dados, que pode ser um banco de dados de testes.

De fato, em um ambiente de produção real, não é aconselhável permitir que os usuários salvem dados diretamente na base de dados através do Swagger ou qualquer outra documentação de API, pois isso pode levar a sérios problemas de segurança e integridade dos dados. Dessa forma, a capacidade de salvar dados através do Swagger é mais útil em fases iniciais de desenvolvimento, prototipagem e ambientes de teste, mas não deve ser exposta em um ambiente de produção real sem as devidas proteções de segurança e validações adequadas.

A lógica por trás de deixar alguém usar o Swagger para salvar dados em uma base de dados útil também é a possibilidade verificar se os dados estão sendo corretamente processados e salvos no banco de dados, além de às vezes, é útil ter uma documentação de API interativa que permita aos desenvolvedores não apenas visualizar a estrutura da API, mas também interagir diretamente com ela para entender melhor como ela funciona.

Quanto à utilização do Swagger à parte do código, o Swagger pode realmente ser utilizado separadamente do projeto, como uma ferramenta independente de documentação, podemos instalá-lo e configurá-lo separadamente do projeto.

Em relação a vários projetos com vários endpoints, é possível colocar todos os endpoints de diferentes sistemas em um único arquivo YAML. O Swagger permite a definição de múltiplos caminhos e endpoints em um único arquivo, facilitando a organização e documentação de diferentes sistemas.

Somado a isso, se estivermos documentando os endpoints de vários sistemas diferentes, podemos usar o Docker para criar e gerenciar diferentes containers para cada sistema. Cada container pode ter sua própria instância do Swagger, permitindo documentar e acessar os endpoints de cada sistema separadamente.

Espero ter ajudado. Caso tenha ficado alguma dúvida, sinta-se à vontade em comunicar, estou à disposição!

Um forte abraço e bons estudos!

Caso este post tenha te ajudado, por favor, marcar como solucionado ✓