Documentação Dinâmica (OpenAPI)

A Documentação Dinâmica é o recurso do Console que gera automaticamente especificações técnicas padronizadas no formato OpenAPI 3.0 (antigo Swagger) para qualquer versão de fluxo publicada na plataforma.

Em vez de exigir a escrita e manutenção manual de arquivos de documentação, o Console inspeciona as configurações de contrato do fluxo em tempo real e consolida a especificação em um documento JSON pronto para ser consumido por desenvolvedores, portais de desenvolvedores (Developer Portals) ou ferramentas de teste (ex: Postman, Insomnia).

Como a Especificação é Gerada

A especificação OpenAPI 3.0 não é estática. Ela é construída dinamicamente agregando o estado real do fluxo, seus contratos de entrada e saída e os mecanismos de validação configurados nas etapas:

┌─────────────────────────────────────────────────────────────────────────┐
│                        FONTES DE DADOS DA VERSÃO                        │
│  - Slugs de Rota (Projeto / Pacote / Fluxo)                             │
│  - Inicializador HTTP (GET, POST, PUT, etc.)                            │
│  - Adaptadores de Entrada (Query, Body, Auth)                           │
│  - Adaptadores de Saída (Status, ID Sessão, Dados, Erro)                │
│  - Etapas de Validação de Entrada (Atributos e Regex)                   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Compilação em Tempo de Execução
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                       ESPECIFICAÇÃO OPENAPI 3.0                        │
│                  GET /v1/geral/openapi/versao/{id}/openapi.json        │
└────────────────────────────────────────────────────────────────────────┘

1. Rotas e Verbos HTTP

Construção de Caminhos (Paths): A especificação gera os endpoints de chamada pública utilizando os slugs cadastrados na hierarquia (/public/{slugProjeto}/{slugPacote}/{slugFluxo}).
Suporte a Execução Assíncrona (ASYNC_ON): Se o adaptador ASYNC_ON estiver configurado na versão, a especificação OpenAPI gera dinamicamente dois caminhos de rota para o fluxo:
Rota Síncrona: /public/{slugProjeto}/{slugPacote}/{slugFluxo} (aguarda o processamento e retorna a resposta formatada).
Rota Assíncrona: /async/public/{slugProjeto}/{slugPacote}/{slugFluxo} (recebe a requisição, dispara a sessão em segundo plano e retorna imediatamente o código HTTP 200 OK com o ID da sessão).
Método HTTP: Define a operação REST com base no Inicializador HTTP cadastrado no fluxo (ex: POST, GET, PUT).

2. Contratos de Entrada (Parâmetros e Payload)

A seção de requisição (requestBody e parameters) é documentada inspecionando os Adaptadores de Entrada e as Etapas de Validação:

Query Params (QUERY_PARAMS_ON): Se o fluxo contiver adaptadores de parâmetros de URL ativados ou uma etapa de validação de entrada (DADOS_ENTRADA) que exija parâmetros de consulta, o Console mapeia cada parâmetro na OpenAPI com seu nome, tipo de dado e regra de obrigatoriedade.
Corpo da Requisição (BODY_JSON / BODY_TEXT): O adaptador de corpo define o Content-Type aceito (application/json ou text/plain). Se o fluxo utilizar o nó de validação de entrada (DADOS_ENTRADA) com esquemas configurados para o corpo da requisição, os campos e suas respectivas Expressões Regulares (Regex) são convertidos automaticamente em esquemas de validação JSON Schema dentro do documento OpenAPI.
Autenticação (AUTH_JWT_BEARER_ON): Se a versão exigir autorização por token, a especificação declara automaticamente o esquema de segurança Bearer JWT no cabeçalho Authorization.

3. Contratos de Saída (Respostas e Códigos HTTP)

A seção de respostas (responses) reflete as regras definidas pelos Adaptadores de Saída:

Códigos de Sucesso: Documenta o retorno esperado como 200 OK (STATUS_SUCESSO_200) ou 201 Created (STATUS_SUCESSO_201).
Estrutura do Payload: Reflete o modelo de resposta formatado pelo adaptador de corpo de resposta (DATA_JSON, DATA_JSON_FLAT ou DATA_SUPPRESS) e pela inclusão de metadados de sessão (SESSAO_FULL) ou ID (ID_BODY ou ID_HEADER).
Respostas de Erro: Mapeia os retornos padrão de erro da plataforma (ex: 400 Bad Request para falhas de validação, 401 Unauthorized para ausência de token e 404 Not Found para rotas não encontradas) com base no adaptador do grupo ERRO (ERRO_FULL ou ERRO_BOLEANO).

Acesso e Visualização no Console

O Console de Gestão disponibiliza a documentação técnica de duas formas:

Endpoint JSON REST

Exposição direta do documento no formato JSON através da rota de integração /v1/geral/openapi/versao/{idVersao}/openapi.json. Esse endpoint pode ser fornecido diretamente a ferramentas externas ou de testes de API.
Interface Gráfica Embutida

A aba Documentação na tela de detalhes da versão renderiza a especificação OpenAPI utilizando um visualizador gráfico interativo. Desenvolvedores podem inspecionar os esquemas de dados, copiar comandos curl e testar as chamadas diretamente pela interface.

Benefícios da Documentação Automática

Sempre Atualizada

Qualquer alteração nos adaptadores ou nas regras de validação das etapas reflete instantaneamente no documento OpenAPI gerado.

Redução de Erros de Integração

Desenvolvedores clientes consultam exatamente as regras de Regex, cabeçalhos e campos aceitos pelo fluxo em tempo de execução.

Padronização

Garante que todos os fluxos criados na empresa sigam rigorosamente a especificação OpenAPI 3.0 sem esforço manual.