Qual a Vantagem do Swagger na Construção da API?

Ao criar o meu projeto, pude aprender que o Swagger permite que você descreva a estrutura de suas APIs para que ela possa ser lida e demonstrada ao desenvolvedor para fins de testes. A capacidade das APIs de descrever sua própria estrutura é a raiz de toda a grandiosidade do Swagger e soube por experiência própria de sua eficiência na documentação. Mas mesmo assim, por que o Swagger é tão grande? Bem, lendo a estrutura da sua API, podemos observar a sua capacidade de construir automaticamente uma documentação bonita e interativa da API.

Também podemos ver ele gerar bibliotecas de cliente automaticamente para sua API em vários idiomas e explorar outras possibilidades, como testes automatizados. O Swagger faz isso solicitando que sua API retorne um YAML ou JSON que contenha uma descrição detalhada de toda a sua API. Este arquivo é essencialmente uma lista de recursos de sua API que adere à 'especificação OpenAPI'. A especificação pede que você inclua informações como:

• Quais são todas as operações que sua API suporta?
• Quais são os parâmetros da sua API e o que ela retorna?
• Sua API precisa de alguma autorização?
• E até coisas divertidas como temos, informações de contato e licença para usar a API.

Você pode escrever uma especificação Swagger para sua API manualmente ou gerá-la automaticamente a partir de anotações em seu código-fonte. Verifique swagger.io/open-source-integrations para obter uma lista de ferramentas que permitem gerar Swagger a partir do código.

Então, eu tenho uma especificação Swagger para minha API. O que agora?

Existem algumas maneiras pelas quais o Swagger pode ajudar a impulsionar ainda mais o desenvolvimento de sua API:

• Usuários que priorizam o design: use o Swagger Codegen para gerar um stub de servidor para sua API. A única coisa que resta é implementar a lógica do servidor – e sua API está pronta para ser lançada!
• Use o Swagger Codegen para gerar bibliotecas de cliente para sua API em mais de 40 idiomas.
• Use a IU do Swagger para gerar documentação de API interativa que permite que seus usuários experimentem as chamadas de API diretamente no navegador.
• Use a especificação para conectar ferramentas relacionadas à API à sua API. Por exemplo, importe a especificação para SoapUI para criar testes automatizados para sua API.
• E mais! Confira as ferramentas comerciais e de código aberto que se integram ao Swagger.

Com isso, fiz uma aplicação básica que consiste em uma lista de controle de convidados de festas e eventos, onde os dados são coletados, como nome, sobrenome e quantidades de acompanhantes, e depois são listados no app web. Porém, foram feitos algumas modificações para melhor explorar as possibilidades disponíveis e aumentar a experiência com a api. Essas visualizações são possíveis por meio do Swagger e JavaDoc.

Projeto no GitHub: Api Controle de Convidados

Obrigado a todos;

Por Adriano Santos