Porque usar Swagger na sua API?

Swagger Header Image

API é o acrônimo de Application Programming Interface ou, em português, Interface de Programação de Aplicativos.

Esta interface é o conjunto de padrões de programação que permite a construção de aplicativos e a sua utilização de maneira não tão evidente para os usuários.

API é a “matrix” dos aplicativos, ou seja, uma interface que roda por trás de tudo: enquanto você usufrui de um aplicativo ou site, a sua API pode estar conectada a diversos outros sistemas e aplicativos. E tudo isso acontece sem que você perceba.

As APIs proporcionam a integração entre sistemas que possuem linguagem totalmente distintas de maneira ágil e segura. Em outras formas de integração de sistemas, o profissional que realiza o trabalho precisa, muitas vezes, instalar recursos compatíveis com o sistema no qual se busca efetuar a integração, gerando um grande trabalho e, consequentemente, atraso na geração de negócios e processos produtivos de uma companhia.

Ciclo de Funcionamento de uma API

As possibilidades disponibilizadas pelo uso das APIs proporcionam para os desenvolvedores de softwares e aplicativos a possibilidade de conectar tecnologias heterogêneas, como diferentes bancos de dados, por exemplo. Além disso, é possível fazer com que funcionalidades e ferramentas específicas de determinados aplicativos sejam utilizadas em outros, sem que isso cause qualquer dificuldade, conforme veremos no tópico a seguir.

Acho que já falamos muito sobre a API, vamos no que interessa agora. Então, para entender como a API funciona e como usá-la é necessário ver a documentação. E a Swagger é uma ótima opção para documentar.

Swagger é um framework para descrição, consumo e visualização de serviços RESTful. E seu grande objetivo é permitir que a documentação possa evoluir no mesmo ritmo da implementação, já que pode ser gerada automaticamente com base em anotações do código, gigantes da tecnologia como a Yelp e a Netflix já usam o Swagger nos seus produtos e projetos.

O Swagger tem um módulo de UI que permite aos developers interagirem com as APIs em sandbox de forma muito intuitiva como podemos ver na imagem abaixo, sem exigir conhecimento da implementação ou mesmo dos parâmetros e opções (que são explícitas na documentação).

Swagger Petstor Exemplo (caso conhecido)

Eu usaria o Swagger porque?

  • Acho a interface amigavél
  • Organização das rotas
  • Posso testar mesmo ai, sem ter de recorrer outros meios
  • Modelagem da API
  • Geração de documentação da API
  • Geração de códigos do Cliente e do Servidor, com suporte a várias linguagens de programação
  • A diferença entre as cores nas rotas me agradam (Kkkkk), e outros N motivos

A especificação OpenAPI, conhecida como OpenAPI Specification (OAS), é uma especificação para arquivos de interface legíveis por máquina para descrever, produzir, consumir e visualizar serviços de uma API RESTful.

A OpenAPI possui um formato JSON definido com campos padronizados (através de um JSON Schema) para que você descreva recursos, modelo de dados, URIs, Content-Types, métodos HTTP aceitos e códigos de resposta. Também pode ser utilizado o formato YAML, que é um pouco mais legível.

Além da OpenAPI, o Swagger provê um ecossistema de ferramentas. As principais são:
— Swagger Editor — para a criação do contrato
— Swagger UI — para a publicação da documentação
— Swagger Codegen — para geração de “esqueletos” de servidores em mais de 10 tecnologias e de clientes em mais de 25 tecnologias diferentes.

Javascript, PHP & Golang Developer | NBA Lover | Sneakerhead

Javascript, PHP & Golang Developer | NBA Lover | Sneakerhead