loading...

Porque usar Swagger na sua API?

arikardnoir profile image Aristoteles Lopes Updated on ・3 min read

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.

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, sem exigir conhecimento da implementação ou mesmo dos parâmetros e opções (que são explícitas na documentação).

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.

Posted on by:

arikardnoir profile

Aristoteles Lopes

@arikardnoir

Software Engineer | NBA Lover | Sneakerhead

Discussion

pic
Editor guide