Gerador de Documentação de API de Webhooks Ativos - Fluxo de trabalho n8n

• Desenvolvedores que gerem múltiplas integrações de API através do n8n.


• Equipas que necessitam de um diretório centralizado e auto-atualizável dos seus endpoints de webhook do n8n.


• Utilizadores que pretendem simplificar a partilha de especificações de API para os seus designs de fluxo de trabalho n8n.


• Especialistas em automação à procura de exemplos avançados da utilização do nó n8n para introspeção.

Gerir numerosos webhooks de fluxos de trabalho n8n pode tornar-se complexo. Este poderoso fluxo de trabalho n8n resolve o problema de visibilidade ao realizar introspeção automática de toda a instância n8n. Utiliza a API interna do n8n para reunir detalhes sobre todos os fluxos de trabalho ativos e os seus nós de webhook incorporados, transformando esses dados numa especificação Swagger 2.0 padrão.

A documentação resultante é apresentada através de uma interface Swagger UI interativa, renderizada diretamente no navegador quando o webhook de ativação (trigger) do n8n é chamado. Isto elimina a necessidade de atualizações manuais da documentação sempre que um novo fluxo de trabalho ou endpoint n8n é implementado, proporcionando um valor significativo para as equipas de DevOps e integração. Além disso, suporta anotações personalizadas nas notas do webhook para documentar corretamente os parâmetros de consulta (query) e de corpo (body), tornando este modelo n8n excecionalmente útil para construir camadas de API robustas.

1. O processo começa com o trigger n8n Get Swagger, que é um Webhook HTTP configurado para responder utilizando um nó a jusante (downstream).


2. O nó n8n n8n executa então um pedido contra a API interna do n8n, recuperando especificamente os detalhes de todas as configurações de fluxo de trabalho n8n atualmente ativos na instância.


3. A lógica central reside no nó n8n Code. Este nó processa os dados JSON brutos do fluxo de trabalho. Identifica todos os nós Webhook e os seus nós correspondentes de Resposta ao Webhook (Respond to Webhook), analisando as ligações para determinar o tipo de resposta (JSON, texto ou redirecionamento).


4. Crucialmente, o nó Code constrói uma string YAML Swagger 2.0, extraindo o caminho (path), método, códigos de resposta e adicionando dinamicamente a documentação de parâmetros se o nó n8n Webhook original tiver anotações relevantes nas suas notas (ex: @query ou @body).


5. Finalmente, o nó n8n Respond to Webhook pega no texto YAML do Swagger gerado e incorpora-o numa estrutura (template) HTML que inicializa o pacote Swagger UI. Isto entrega uma página de documentação interativa diretamente ao requerente, oferecendo uma fonte de documentação completa e dinâmica gerada pelo próprio fluxo de trabalho n8n.

1. Importe o JSON do fluxo de trabalho fornecido para a sua instância n8n.


2. Configuração de Credenciais: Este fluxo de trabalho n8n requer credenciais para o nó n8n (Passo 2). Deve configurar uma credencial de 'API n8n', tipicamente gerando um Token de Acesso Pessoal (PAT) nas suas definições do n8n.


3. Configurar Anotações (Opcional mas Recomendado): Para garantir que a sua documentação de API inclui parâmetros, abra o nó Webhook do n8n em qualquer um dos seus fluxos de trabalho ativos e utilize o campo 'Notas' para adicionar definições de parâmetros, seguindo a sintaxe detalhada na nota adesiva do fluxo de trabalho (ex: // @query my_id string O identificador do recurso).


4. Ativar: Guarde e ative o novo fluxo de trabalho n8n.


5. Acesso: Aceda à sua documentação ao vivo acedendo ao URL do webhook definido (ex: https://sua-instancia-n8n/webhook/swagger).

Get Swagger (Webhook Trigger): O trigger n8n inicial. Escuta na rota /swagger e utiliza a configuração responseNode para aguardar o resultado final.
n8n (nó n8n): Busca todos os dados de fluxos de trabalho n8n ativos usando a API interna do n8n. Isto garante que a documentação está sempre atualizada com os endpoints atualmente implementados.
Code (nó de Código Personalizado): Este é o motor de automação deste modelo n8n. Analisa a estrutura do fluxo de trabalho, determina as ligações de resposta do webhook, extrai notas de parâmetros opcionais e formata meticulosamente os dados numa string YAML Swagger 2.0 válida. Inclui lógica complexa (findValidTargets) para o rastreamento das ligações entre um nó n8n Webhook e um nó n8n Respond to Webhook.
Respond to Webhook (nó de Ação Final): O nó n8n final que empacota os dados YAML do Swagger gerados numa estrutura (wrapper) HTML. Esta estrutura carrega os ativos de frontend do Swagger UI, apresentando a pré-visualização interativa da documentação da API com base nos dados ao vivo gerados pelo próprio fluxo de trabalho n8n.