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

Seguindo os passos da figura 2.1, vamos criar um bloco de programação para adicionar um pet à petstore. Selecione apenas a opção bloco de programação no método addPet e deixe as outras opções maracadas como Nenhum.

Para visualizar a função importada, é necessário criar um bloco de programação (destaque 1 da figura 2.2), para este exemplo, criamos um bloco chamado "pet". Acesse a categoria "Swagger Petstore - pet" (2), essa nomenclatura informa o nome da api e da tag importada, respectivamente. Nesta categoria consta a função "Add a new pet to the store". temos somente essa função pois selecionamos somente o método addPet na hora da importação, se tivéssemos optado por selecionar bloco de programação no endpoit pet, todas as funções seriam importadas para a categoria.

Image Added

Figura 2.2 - Categoria criada após a importação do método como bloco de programação

Fonte de dados