OpenAPI é Necessário Saber

OpenAPI Site

OpenAPI Github

O OpenAPI é uma especificação aberta e padronizada para descrever APIs RESTful, que surgiu a partir do Swagger desenvolvido pela SmartBear. Em 2015, a OpenAPI Initiative (OAI) foi criada sob a Linux Foundation, e o Swagger Specification foi doado para a OAI, tornando-se a base do que hoje conhecemos como OpenAPI Specification (OAS). Desde então, o OpenAPI evoluiu como o principal padrão para descrever APIs RESTful.

Em alguma momento da sua carreira você vai se deparar com a necessidade de entender melhor sobre APIs.

APIs (Application Programming Interfaces) são interfaces que permitem a comunicação entre diferentes sistemas, softwares ou componentes de um software. Elas definem regras e protocolos que permitem que um sistema acesse funcionalidades ou dados de outro de maneira estruturada e segura.

Poderíamos comparar uma API com um menu de restaurante:

• O menu mostra o que está disponível (serviços ou dados que o sistema oferece).
• Você (o cliente) faz um pedido com base no menu (a solicitação para a API).
• A cozinha (o sistema de backend) processa seu pedido e retorna o prato (o resultado) sem que você precise saber como ele foi preparado.

Existem vários tipos de APIs sendo a mais usada o que chamamos de APIs RESTful que é baseada nos protocolo HTTP e segue o estilo arquitetural REST (usando métodos como GET, POST, PUT, DELETE, etc).

O OpenAPI e as APIs RESTful estão conectados porque o OpenAPI é uma especificação que descreve como uma API RESTful deve funcionar. Ele fornece um padrão para documentar e estruturar APIs RESTful, tornando-as mais fáceis de entender, implementar e consumir.

A especificação sozinha já tem muito valor e pode ser consumida por diferentes ferramentas e processos, tornando-a útil mesmo sem uma interface visual. A UI é um complemento que melhora a experiência dos desenvolvedores, mas não é um requisito para usar OpenAPI. Através dessa UI podemos ter exemplos como esses e inclusive podemos testar no botão Try It Out.

É necessário mitigar riscos sobre expor essa documentação publicamente, pois atacantes podem explorar os endpoints e tentar diferentes tipos de ataques. Mais pra frente vamos entender como mitigar esses riscos.

OpenAPI vs APIs RESTful

• APIs RESTful: São um estilo arquitetural para construir APIs que utilizam o protocolo HTTP e padrões como:

  • Recursos representados por URLs (e.g., /users, /orders).
  • Métodos HTTP como GET, POST, PUT, DELETE para operações CRUD.
  • Dados em formatos como JSON ou XML.

• OpenAPI: É uma especificação usada para descrever APIs RESTful. Ele define:

  • Os endpoints disponíveis.
  • Os métodos HTTP suportados.
  • Os parâmetros que podem ser enviados (query, path, headers, body).
  • Os tipos de dados esperados (e.g., JSON, XML).
  • As respostas retornadas (códigos de status e estrutura do payload).

Benefícios do OpenAPI para APIs RESTful

• Documentação automática: Ferramentas como Swagger UI podem gerar documentação interativa baseada em arquivos OpenAPI.
• Padronização: Define um formato claro e consistente para projetar APIs.
• Validação: As ferramentas podem validar se uma API está aderindo à especificação definida.
• Mock APIs: Permite criar versões falsas da API para desenvolvimento antes da implementação real.
• Geradores de código: Pode gerar clientes e servidores automaticamente em várias linguagens.
• Amplamente utilizado em Api Gateways: A maioria dos Api Gateways utilizam arquivos que definem a Api com uma configuração OpenAPI.
• Agnostico: Não é criado para nenhuma tecnolgia e linguagem específica.
• Suporte: Apoiado vários grandes players do mercado. Biblioteca disponível em práticamente todas as linguagens.

OpenAPI é considerado o padrão para descrever APIs.

OpenAPI 2.0 vs 3.0

A diferença entre OpenAPI 2.0 e OpenAPI 3.0 está em melhorias significativas na funcionalidade, flexibilidade, e na maneira como os recursos de APIs são descritos, logo o SCHEMA foi mudado e devemos nos atentar a isso. A principal mudança foi tornar os componentes mais reutilizáveis, padronizados e fáceis de definir.

Vamos focar no estudo já na 3.0 sendo que este é o futuro.

OpenAPI na IDE

A especificação é escrita em arquivos YAML ou JSON . Para ajudar a escrever estas especificações e respeitar o SCHEMA temos plugins nas IDEs que facilitam bastante. Por vezes nos trazem templates prontos para preencher. Particulamente utilizar YAML facilita bastante a leitura além de ser menos verboso.

Por exemplo temos no VSCode este plugin.

Uma vez instalado já temos ele aparecendo do lado e quando pedimos para criar um template já virá pronto nos ajudando inclusive com um explorer do lado dividindo as sessões.

Então não é necessário sofrer tanto assim, inclusive podemos ver como fica a UI.

OpenAPI Tools

Existem várias ferramentas que ajudam no desenvolvimento:

• Conversores
• Validadores
• Editores
• Mock Services
• Geradores de SDK
• Documentação.

Uma lista de tools conhecidas pode ser encontrada em https://tools.openapis.org/.

Swagger Hub

Já vimos que podemos usar somente plugins dentro da IDE que nos ajudem a especificar, mas antes é bom saber que a Smart Bear, que fez a doação do Swagger para a iniciativa OpenAPI, possui diversas ferramentas comerciais e open source que facilitam no desenvolvimento de APIs através do Swagger Hub.

Para aprender, se for facilitar a sua vida, pode fazer um free account somente para você, uma vez que é free somente para 1 pessoa. O Swagger Hub tem um conjunto de ferramentas incluindo um editor.