OpenAPI

O que é o OpenAPI?

O OpenAPI é um padrão de documentação para APIs. Com ele, você pode visualizar, testar e exportar as informações das APIs de forma organizada. Na prática, ele transforma os fluxos da sua aplicação em uma documentação clara, permitindo que você entenda e interaja com essas APIs.

Onde encontrar o botão OpenAPI?

Na tela de fluxos, no canto superior direito, existe um botão chamado OpenAPI. Ao clicar nele, será aberta uma janela (modal) com as opções de Exportar, Visualizar e alterar o Acesso à documentação.

Opções da Modal OpenAPI

Selecionar Stage

• O campo Stage é uma lista onde você escolhe o ambiente (stage) que deseja documentar.

• Você pode selecionar:

  • Um stage → se quiser apenas visualizar a documentação ou exportar o arquivo somente de um stage.

  • Vários stages → se quiser exportar a documentação em vários arquivos .json de cada stage.

Exportar

• Depois de selecionar um ou mais stages, clique em Exportar.

• Para cada stage selecionado será gerado um arquivo de download .json .

• Esse arquivo segue a especificação OpenAPI e contém a descrição de todos os fluxos com trigger Rest publicados naquele stage e daquele projeto onde o fluxo se encontra.

• Esses arquivos podem ser usados em outras ferramentas que aceitam OpenAPI, como Postman ou Swagger.

Visualizar

• Disponível apenas quando você seleciona um único stage.

• Ao clicar em Visualizar, uma nova aba será aberta mostrando a documentação no formato Swagger.

• Nessa aba, você pode:

  • Ver todos os fluxos com trigger Rest como se fossem endpoints de API.

  • Explorar detalhes de cada API (método, parâmetros, corpo da requisição, etc.).

  • Testar os endpoints usando a função Try-out.

  • Inserir dados de Authorization para chamadas protegidas.

  • Editar e enviar request bodies diretamente pela interface.

Acesso à Documentação

Essa opção define quem pode acessar a documentação Swagger quando ela é aberta em uma nova aba:

• Privado (Padrão)

  • Apenas usuários logados na aplicação podem acessar.

  • Se você compartilhar o link com outra pessoa, ela precisará estar logada para visualizar.

• Público

  • Qualquer pessoa com o link poderá acessar, mesmo sem estar logada na aplicação.

  • Útil para compartilhar a documentação com parceiros externos ou equipes que não possuem acesso ao sistema.

Como configurar as especificações dos fluxos

Para que a documentação OpenAPI seja gerada corretamente, é importante configurar tanto a requisição quanto a resposta dos fluxos com trigger Rest.

Configuração da Requisição

1. Acesse o fluxo que possui a trigger do tipo Rest.

2. Abra as configurações da trigger.

3. Na aba Body, insira um JSON Schema com as especificações da requisição.

   • Esse schema define a estrutura esperada do corpo da requisição (exemplo: campos, tipos, descrições).

   • Exemplo:

     Copy

     {
       "$schema": "https://json-schema.org/draft/2019-09/schema",
       "title": "Novo Cliente",
       "description": "API para criar um novo cliente",
       "type": "object",
       "properties": {
         "clientePayload": {
           "description": "Objeto do cliente",
           "type": "object",
           "properties": {
             "id": {
               "description": "ID do cliente",
               "type": "string"
             },
             "nome": {
               "description": "Nome do cliente",
               "type": "string"
             }
           }
         }
       }
     }

Na imagem em anexo, é possível ver o campo destacado onde o JSON Schema deve ser configurado.

Configuração do Response

1. Acesse o fluxo e abra o step Fim (última etapa do fluxo).

2. Clique para expandir o status response desejado conforme mostra a primeira imagem abaixo.

3. Na aba OAS, insira um JSON Schema com as especificações da resposta da API.

   • Esse schema define como será o retorno da requisição (status, estrutura de dados, campos).

   • Exemplo:

     Copy

     {
       "type": "object",
       "properties": {
         "status": {
           "description": "Status da operação",
           "type": "string"
         },
         "mensagem": {
           "description": "Mensagem de retorno",
           "type": "string"
         }
       }
     }

Na segunda imagem em anexo, você encontra a aba “OAS” onde o JSON Schema deve ser configurado.