Definição

A Especificação OpenAPI (OAS) define uma descrição de interface padrão, independente de linguagem de programação, para APIs HTTP, o que permite tanto humanos quanto computadores descobrirem e entenderem as capacidades de um serviço sem exigir acesso ao código-fonte, documentação adicional ou inspeção do tráfego de rede. Quando devidamente definida via OpenAPI, um consumidor pode entender e interagir com o serviço remoto apenas configurando alguns parâmetros na tela de importação do serviço. Semelhante ao que as descrições de interface fizeram para programação em níveis mais baixos, a especificação OpenAPI remove a necessidade de adivinhação ao chamar um serviço. Para mais informações, acesse a documentação oficial do OpenAPI Specification.

Importando OpenAPI/Swagger

Acesse o menu Projeto > Importar e na janela que será exibida, escolha a opção OpenAPI/Swagger, por fim, clique em Avançar. como mostra a figura abaixo.

Figura 1 - Importando OpenAPI/Swagger

Configuração

Após selecionar a opção OpenAPI/Swagger, a janela de configuração da funcionalidade será exibida, preencha os campos e clique em Avançar para dar continuidade ao processo.

Figura 2 - Configuração da janela OpenAPI

• URL:  campo destinado à informar o caminho da API. Ao preencher este campo, os campos das propriedades Url base e Namespace serão preenchidos automaticamente.
• URL base: ponto de entrada principal para os recursos disponíveis da API. É a parte fixa da URL que geralmente permanece constante para todas as requisições feitas à API. A URL base, quando combinada com caminhos específicos de recurso, permite que os clientes acessem endpoints específicos da API.
• Categoria:  <TODO>
• Usar tags como categoria: crua categorias novas de blocos de programação baseadas nas tags da API.
• Namespace: campo preenchido automaticamente ao inserir a URL.
• Cabeçalhos: os campos de cabeçalho são utilizados para situações em que o usuário precise acessar algum recurso da API que precise de autenticação.
  
  • Chave: nome do cabeçalho, por exemplo, "Authorization", "Content-Type", "X-AUTH-TOKEN".
  • Valor: conteúdo ou o valor atribuído a essa chave

Figura 2.1 - Configuração das tags da API

Após clicar em "Avançar", a janela de configuração das tags será exibida. No exemplo apresentado acima, temos três tags: pet, store e user (destaque 1 da figura 2.1). Ao expandir cada tag, podemos visualizar seus respectivos endpoints (2), os quais apresentam seus métodos (verbos HTTP) (3). É possível configurar cada tag ou método individualmente para importar os dados da API como Blocos de Programação, Fonte de Dados (webservice) ou optar por não importar nada, selecionando a opção "Nenhum". Além disso, é possível selecionar uma das três opções de importaçãodiretamente na tag, de modo que a opção escolhida seja aplicada para todos os endpoints e, consequentemente, para os métodos.

Exemplos

Para ilustrar, vamos apresentar dois exemplos: inicialmente, vamos desenvolver blocos de programação utilizando uma API, importando-a via OpenAPI/Swagger. Em seguida, criaremos uma fonte de dados para extrair registros específicos dessa API. Ambos os exemplos serão baseados na API PetStore.

Blocos de programação

Fonte de dados