自动生成活跃 Webhook API 文档工具 - n8n 工作流

• 管理着通过 n8n 进行的多 API 对接的开发者。


• 需要一个集中化、自动更新的 n8n Webhook 端点目录的团队。


• 希望简化分享 n8n 工作流设计 API 规范的用户。


• 正在寻找使用 n8n 节点进行自省（Introspection）的高级用例的自动化专家。

管理大量 n8n 工作流的 Webhook 可能会变得很复杂。这个强大的 n8n 工作流通过自动自省整个 n8n 实例来解决可见性问题。它使用 n8n 内部 API 来收集关于所有活跃工作流及其内嵌 Webhook 节点的信息，并将这些数据转换成标准的 Swagger 2.0 规范。

生成的文档会在调用 n8n 触发器 Webhook 时，直接在浏览器中通过交互式的 Swagger UI 展示出来。这消除了每次部署新的 n8n 工作流或端点时手动更新文档的麻烦，为 DevOps 和集成团队带来了巨大价值。此外，它支持在 Webhook 备注中使用自定义注释来准确记录查询和请求体参数，这使得该 n8n 模板在构建健壮的 API 层方面极其有用。

1. 此流程始于 Get Swagger n8n 触发器，它是一个 HTTP Webhook，配置为使用下游节点进行响应。


2. n8n n8n 节点随后对 n8n 内部 API 执行请求，专门获取实例中所有当前活跃的 n8n 工作流配置的详情。


3. 核心逻辑位于 Code n8n 节点中。该节点处理原始的工作流 JSON 数据。它会识别出所有的 Webhook 节点及其对应的“响应 Webhook”节点，分析它们之间的连接以确定响应类型（JSON、文本或重定向）。


4. 关键在于，Code 节点会构建一个 Swagger 2.0 的 YAML 字符串，提取路径、方法、响应码，并根据原始 Webhook n8n 节点备注中是否有相关注释（例如 @query 或 @body）来动态添加参数文档。


5. 最后，Respond to Webhook n8n 节点将生成的 Swagger YAML 文本嵌入到一个 HTML 模板中，该模板会初始化 Swagger UI 资源包。这会直接将一个交互式的文档页面返回给请求者，提供了由 n8n 工作流自身生成的完整、动态的文档源。

1. 将提供的 n8n 工作流 JSON 导入到您的 n8n 实例中。


2. 凭证设置： 此 n8n 工作流的第 2 步（n8n 节点）需要凭证。您必须配置一个“n8n API”凭证，通常是在您的 n8n 设置中生成一个个人访问令牌 (PAT)。


3. 配置注释（可选，但推荐）： 为确保 API 文档包含参数信息，请在您任一活跃工作流中打开 Webhook n8n 节点，并使用“备注”(Notes) 字段根据工作流中“便签”(sticky note) 详述的语法添加参数定义（例如 // @query my_id string The resource identifier）。


4. 激活： 保存并激活新的 n8n 工作流。


5. 访问： 访问定义的 Webhook URL（例如 https://your-n8n-instance/webhook/swagger）来访问您的实时文档。

Get Swagger (Webhook 触发器): n8n 的起始触发器。它监听 /swagger 路径，并使用 responseNode 配置等待最终输出。
n8n (n8n 节点): 使用 n8n 内部 API 获取所有活跃的 n8n 工作流数据。这确保了文档内容与当前已部署的端点保持同步。
Code (自定义代码节点): 这是此 n8n 模板的自动化引擎。它解析工作流结构，确定 Webhook 响应连接，提取可选的参数备注，并精心格式化数据成有效的 Swagger 2.0 YAML 字符串。它包含了复杂的逻辑 (findValidTargets) 用于追踪 Webhook n8n 节点和“响应 Webhook”n8n 节点之间的连接。
Respond to Webhook (最终动作节点): 最后一个 n8n 节点，它将生成的 Swagger YAML 数据打包到一个 HTML 包装器中。该包装器加载 Swagger UI 前端资源，并根据 n8n 工作流实时生成的数据渲染出交互式 API 文档预览。