Générateur de Documentation API pour Webhooks Actifs - Workflow n8n

• Développeurs gérant de multiples intégrations API via n8n.


• Équipes nécessitant un répertoire centralisé et auto-mis à jour de leurs points de terminaison webhook n8n.


• Utilisateurs souhaitant simplifier le partage des spécifications API pour leurs conceptions de flux de travail n8n.


• Spécialistes de l'automatisation recherchant des exemples avancés d'utilisation du nœud n8n pour l'introspection.

La gestion de nombreux webhooks de flux de travail n8n peut devenir complexe. Ce puissant flux de travail n8n résout le problème de visibilité en inspectant automatiquement l'ensemble de l'instance n8n. Il utilise l'API interne de n8n pour collecter les détails de tous les flux de travail actifs et de leurs nœuds Webhook intégrés, transformant ces données en une spécification Swagger 2.0 standard.

La documentation résultante est présentée via une interface Swagger UI interactive rendue directement dans le navigateur lorsque le webhook de déclenchement n8n est appelé. Cela élimine le besoin de mises à jour manuelles de la documentation chaque fois qu'un nouveau flux de travail ou point de terminaison n8n est déployé, offrant une valeur significative pour les équipes DevOps et d'intégration. De plus, il prend en charge les annotations personnalisées dans les notes des webhooks pour documenter correctement les paramètres de requête et de corps, rendant ce modèle n8n exceptionnellement utile pour construire des couches API robustes.

1. Le processus commence par le déclencheur n8n Get Swagger, qui est un Webhook HTTP configuré pour répondre via un nœud en aval.


2. Le nœud n8n n8n exécute ensuite une requête contre l'API interne de n8n, récupérant spécifiquement les détails de toutes les configurations de flux de travail n8n actuellement actives dans l'instance.


3. La logique principale réside dans le nœud n8n Code. Ce nœud traite les données JSON brutes du flux de travail. Il identifie tous les nœuds Webhook et leurs nœuds correspondants Respond to Webhook, analysant les connexions pour déterminer le type de réponse (JSON, texte ou redirection).


4. De manière cruciale, le nœud Code construit une chaîne YAML Swagger 2.0, extrayant le chemin, la méthode, les codes de réponse, et ajoutant dynamiquement la documentation des paramètres si le nœud n8n Webhook d'origine possède des annotations pertinentes dans ses notes (par exemple, @query ou @body).


5. Enfin, le nœud n8n Respond to Webhook prend le texte YAML Swagger généré et l'intègre dans un modèle HTML qui initialise le bundle Swagger UI. Cela délivre une page de documentation interactive directement à l'interrogateur, offrant une source de documentation complète et dynamique générée par le flux de travail n8n lui-même.

1. Importer le JSON du flux de travail n8n fourni dans votre instance n8n.


2. Configuration des identifiants : Ce flux de travail n8n nécessite des identifiants pour le nœud n8n (Étape 2). Vous devez configurer un identifiant 'API n8n', généralement en générant un Jeton d'Accès Personnel (PAT) dans vos paramètres n8n.


3. Configuration des Annotations (Optionnel mais recommandé) : Pour garantir que votre documentation API inclue les paramètres, ouvrez le nœud Webhook n8n dans l'un de vos flux de travail actifs et utilisez le champ 'Notes' pour ajouter des définitions de paramètres, en suivant la syntaxe détaillée dans la note mémo du flux de travail (par exemple, // @query my_id string L'identifiant de la ressource).


4. Activation : Enregistrez et activez le nouveau flux de travail n8n.


5. Accès : Accédez à votre documentation en direct en appelant l'URL du webhook définie (par exemple, https://votre-instance-n8n/webhook/swagger).

Get Swagger (Déclencheur Webhook) : Le déclencheur n8n de départ. Il écoute sur le chemin /swagger et utilise la configuration responseNode pour attendre le résultat final.
n8n (Nœud n8n) : Récupère toutes les données des flux de travail n8n actifs en utilisant l'API interne de n8n. Cela garantit que la documentation est toujours à jour avec les points de terminaison actuellement déployés.
Code (Nœud de Code Personnalisé) : C'est le moteur d'automatisation de ce modèle n8n. Il analyse la structure du flux de travail, détermine les connexions de réponse des webhooks, extrait les notes de paramètres optionnelles, et formate méticuleusement les données en une chaîne YAML Swagger 2.0 valide. Il inclut une logique complexe (findValidTargets) pour tracer les connexions entre un nœud n8n Webhook et un nœud n8n Respond to Webhook.
Respond to Webhook (Nœud d'Action Final) : Le nœud n8n final qui emballe les données YAML Swagger générées dans un wrapper HTML. Ce wrapper charge les actifs frontend de Swagger UI, rendant l'aperçu de la documentation API interactive basé sur les données en direct générées par le flux de travail n8n.