활성 웹훅 API 문서 자동 생성기 - n8n 워크플로우

• n8n을 통해 다수의 API 통합을 관리하는 개발자


• n8n 웹훅 엔드포인트에 대한 중앙 집중식 자동 업데이트 디렉터리가 필요한 팀


• n8n 워크플로우 설계의 API 사양 공유를 간소화하고 싶은 사용자


• 인스펙션(Introspection)을 위한 n8n 노드 활용 고급 예제를 찾는 자동화 전문가

다수의 n8n 워크플로우 웹훅을 관리하는 것은 복잡해질 수 있습니다. 이 강력한 n8n 워크플로우는 n8n 인스턴스 전체를 자동으로 검사(인스펙션)하여 가시성 문제를 해결합니다. 내부 n8n API를 사용하여 활성된 모든 워크플로우와 내장된 웹훅 노드의 세부 정보를 수집하고, 이 데이터를 표준 Swagger 2.0 사양으로 변환합니다.

생성된 문서는 n8n 트리거 웹훅 호출 시 브라우저에 직접 렌더링되는 인터랙티브한 Swagger UI를 통해 제공됩니다. 이를 통해 새로운 n8n 워크플로우나 엔드포인트가 배포될 때마다 문서를 수동으로 업데이트할 필요가 없어 DevOps 및 통합 팀에 상당한 가치를 제공합니다. 또한, 웹훅 노트에 있는 커스텀 어노테이션을 지원하여 쿼리 및 본문 파라미터를 정확하게 문서화하므로, 이 n8n 템플릿은 안정적인 API 계층 구축에 매우 유용합니다.

1. 프로세스는 Get Swagger n8n 트리거에서 시작되며, 이는 후속 노드를 사용하여 응답하도록 설정된 HTTP 웹훅입니다.


2. n8n n8n 노드가 내부 n8n API를 대상으로 요청을 실행하여 현재 인스턴스 내 모든 활성 n8n 워크플로우 구성의 세부 정보를 검색합니다.


3. 핵심 로직은 Code n8n 노드에 있습니다. 이 노드는 원시 워크플로우 JSON 데이터를 처리합니다. 웹훅 노드와 해당 응답 노드(Respond to Webhook)를 식별하고 연결을 분석하여 응답 유형(JSON, 텍스트 또는 리디렉션)을 결정합니다.


4. 중요하게도, Code 노드는 Swagger 2.0 YAML 문자열을 구성하며, 경로, 메서드, 응답 코드를 추출하고 원본 웹훅 n8n 노드 노트에 관련 어노테이션(예: @query 또는 @body)이 있는 경우 파라미터 문서를 동적으로 추가합니다.


5. 마지막으로 Respond to Webhook n8n 노드는 생성된 Swagger YAML 텍스트를 가져와 Swagger UI 번들을 초기화하는 HTML 템플릿에 내장합니다. 이를 통해 n8n 워크플로우 자체가 생성한 완전하고 동적인 문서 소스를 요청자에게 직접 제공합니다.

1. 제공된 n8n 워크플로우 JSON을 n8n 인스턴스로 가져옵니다.


2. 자격 증명 설정: 이 n8n 워크플로우는 n8n 노드(2단계)에 대한 자격 증명이 필요합니다. n8n 설정 내에서 개인 액세스 토큰(PAT)을 생성하여 'n8n API' 자격 증명을 구성해야 합니다.


3. 어노테이션 구성 (선택 사항이지만 권장): API 문서에 파라미터가 포함되도록 하려면 활성 워크플로우의 웹훅 n8n 노드를 열고 '노트' 필드를 사용하여 워크플로우의 스티커 노트에 설명된 구문(예: // @query my_id string 리소스 식별자)에 따라 파라미터 정의를 추가합니다.


4. 활성화: 새 n8n 워크플로우를 저장하고 활성화합니다.


5. 접근: 정의된 웹훅 URL(예: https://your-n8n-instance/webhook/swagger)을 호출하여 라이브 문서에 접근합니다.

Get Swagger (웹훅 트리거): 시작 n8n 트리거입니다. /swagger 경로를 수신 대기하며 최종 출력을 기다리기 위해 responseNode 구성을 사용합니다.
n8n (n8n 노드): 내부 n8n API를 사용하여 모든 활성 n8n 워크플로우 데이터를 가져옵니다. 이를 통해 문서가 현재 배포된 엔드포인트와 항상 최신 상태로 유지됩니다.
Code (커스텀 코드 노드): 이 n8n 템플릿의 자동화 엔진입니다. 워크플로우 구조를 구문 분석하고, 웹훅 응답 연결을 결정하며, 선택적 파라미터 노트를 추출하고, 데이터를 유효한 Swagger 2.0 YAML 문자열로 세심하게 포맷합니다. 웹훅 n8n 노드와 응답 n8n 노드 간의 연결 추적을 위한 복잡한 로직(findValidTargets)이 포함되어 있습니다.
Respond to Webhook (최종 실행 노드): 생성된 Swagger YAML 데이터를 HTML 래퍼로 패키징하는 최종 n8n 노드입니다. 이 래퍼는 Swagger UI 프런트엔드 에셋을 로드하여 n8n 워크플로우가 생성한 라이브 데이터를 기반으로 인터랙티브한 API 문서 미리보기를 렌더링합니다.