Question

swagger-cli 순환 참조시 오류가 발생합니다. 다른 모듈이 있나요?

Answer 1

swagger-cli(내부의 swagger-parser)는 dereference() 단계에서 순환 참조(circular $ref)를 완전히 해소하려다 오류가 발생할 수 있습니다. 순환 참조를 지원하거나 번들링 단계에서 순환을 유지해주는 대안 라이브러리를 소개합니다.

1. @apidevtools/json-schema-ref-parser

   • 외부 파일 참조와 순환 참조를 모두 지원합니다.
   • bundle() 메서드를 사용하면 내부 $ref는 유지하면서도 순환 오류 없이 하나의 객체로 묶을 수 있습니다.
     ```js import $RefParser from '@apidevtools/json-schema-ref-parser';

   async function bundleSpec() { const parser = new $RefParser(); // bundle: 순환 참조를 보존하며 외부 파일을 하나로 묶음 const bundled = await parser.bundle('openapi.yaml'); console.log(bundled); } bundleSpec(); ```
   (APIDevTools/json-schema-ref-parser - GitHub, json-schema-ref-parser - npm)

2. @stoplight/json-schema-ref-parser

   • Stoplight 생태계에서 제공하는 포크 버전으로, API 사용법은 동일하며 Stoplight 도구체인과 통합이 쉽습니다.
     (@stoplight/json-schema-ref-parser - npm)

3. 경량 json-ref-parser

   • cuongurus/json-ref-parser는 매우 가볍게 설계된 $ref 해석기입니다.
   • 순환 및 그래프 형태의 참조도 처리할 수 있습니다.
     (GitHub - cuongurus/json-ref-parser: Extremely light weight way to resolve jsonschema ...)

4. Redocly CLI (@redocly/cli)

   • redocly bundle api.yaml -o bundled.yaml 커맨드로 멀티파일 스펙을 단일 파일로 묶어 줍니다.
   • 다만 아직 내부 순환 참조를 “해소”하는 기능은 없고, 외부 파일을 합치는 용도로만 동작하니 주의하세요.
     (bundle - Redocly)

---

권장

가장 널리 쓰이고 문서화도 잘 되어 있는 @apidevtools/json-schema-ref-parser를 사용해 보시는 것을 추천드립니다. bundle()으로 묶으면 순환 참조를 유지하며 하나의 객체로 다룰 수 있어, swagger-cli에서 겪던 순환 오류를 피할 수 있습니다.