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. 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 a 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: apresenta as categorias existentes dos blocos de programação do Cronapp. Escolhendo uma das categorias, as funções da API que foram importadas como blocos de programação serão inseridas na categoria escolhida. Também é possível escrever neste campo.
• Usar tags como categoria: cria 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 não importar nenhum recurso, selecionando a opção "Nenhum". Além disso, é possível selecionar uma das três opções de importação diretamente 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 para a tag "pet" 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 a Petstore. Selecione apenas a opção "Bloco de programação" no método "addPet" e deixe as outras opções marcadas 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 servidor 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" no momento 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.

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

Para ilustrar a utilização deste bloco, primeiramente precisamos vincular a função a um formulário de referência, consulte a documentação Bloco de programação para mais detalhes. Neste exemplo, adicionaremos um novo animal passando seu nome, para isso criamos uma função cujo o parâmetro do JSON, "name", aqui representado pelo parâmetro "nameAnimal", será passado pelo usuário através de um campo do formulário. Para isso, pegamos a estrutura do JSON que é criado ao adicionar um novo animal e a concatenamos com a variável do parâmetro, essa informação será armazenada em uma variável que nomeamos como "json".

Utilizamos o bloco de tratamento de exceção para ter um controle sobre a execução da função obtida pela API, no parâmetro "body" inserimos a variável que armazena o "json" criado anteriormente. Em uma view web, criamos um formulário que contém um componente entrada de texto, um botão para chamar a função e um componente área de texto, que irá exibir o resultado da requisição através do bloco Alterar valor do campo quando o usuário adicionar o novo pet. Por fim, uma notificação será exibida em caso de sucesso ou erro. O parâmetro conexão será explicado mais a frente.

{ "id": 44, "category": { "id": 0, "name": "string" }, "name": "
<variavelDoParametro>
 ","photoUrls": [ "string" ], "tags": [ { "id": 0, "name": "string" } ], "status": "available" }

Figura 2.3 - Função para adicionar um novo pet a petstore

O resultado da execução da função pode ser conferido abaixo (destaque 1 da figura 2.4).

Figura 2.4 - Resultado da execução da função

Autenticação via bloco

O bloco Nova Conexão, em destaque na figura abaixo, sempre será criado ao importarmos uma OpenAPI como blocos de programação. Este bloco é utilizado quando há a necessidade de acessar algum recurso privado da API. No exemplo da figura abaixo, estamos obtendo os registros de usuários de uma outra aplicação do Cronapp, que contém alguns recursos que somente usuários que possuem um token de autenticação podem acessar. No primeiro parâmetro do bloco, estamos informando o "Caminho Base" da aplicação que queremos obter o recurso, no segundo parâmetro, "Cabeçalhos", passamos a chave e o valor, neste caso, x-auth-token e o token de autenticação, respectivamente. Todas essas informações são acopladas ao bloco obterRegistroget, função criada a partir da OpenAPI.

Figura 3 - Autenticação via bloco de programação

Fonte de dados

Para este exemplo, exibiremos em um formulário de pesquisa web os animais com status "available" da fonte de dados. Importe a OpenAPI da PetStore e siga os passos apresentados na figura 2. Ao chegar na janela de especificações, selecione como Fonte de dados o endpoit /pet/findByStatus e finalize o processo.

Após importar o recurso como Fonte de dados, é necessário editá-lo. Acesse o menu do sistema (destaque 1 da figura 4) e, em seguida, clique no ícone da fonte de dados (2), esse recurso também pode ser acessado através do menu Projeto, ou a partir do componente visual Fonte de dados. As fontes de dados importadas pela OpenAPI não podem ser modificadas, para editá-las precisamos fazer uma cópia, clicando no ícone de edição (3), uma caixa de confirmação será exibida, clique em "OK" para continuar. Dessa forma, o Cronapp copiará automaticamente a fonte em questão.

Figura 4 - Visualizando a fonte de dados importada

A janela de edição da fonte de dados será aberta automaticamente, é possível vê-la na árvore de arquivos do diretório (destaque 1 da figura 4.1). Alteramos seu identificador (2) para "AnimalStatus" e na aba Filtro, definimos o parâmetro "status" como "available".

Figura 4.1 - Editando a Fonte de dados

Feito isso, criaremos uma view para visualizar esses dados. Acesse a fonte de dados criada e clique com o botão direito sobre ela, em seguida, escolha a opção Ação > Criar visão para a entidade (destaque 1 da figura 4.2). O tipo de modelo que utilizaremos será o Formulário de Pesquisa Web (2), altere o nome do arquivo (3) e avance até finalizar o processo.

Figura 4.2 - Criando o Formulário de Pesquisa Web

Execute o projeto e acesse a view criada, o resultado da configuração pode ser conferido abaixo.

Figura 4.3 - Formulário de Pesquisa Web exibindo os animais com o status available