fix swagger $ref resolve error

Author: qazsato

package-lock.json

@@ -24,11 +24,12 @@
   "author": "qazsato <qazsato@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^11.7.2",
+    "@apidevtools/json-schema-ref-parser": "^14.1.0",
     "commander": "^12.1.0",
     "ejs": "^3.1.10",
     "inquirer": "^12.0.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "safe-stable-stringify": "^2.5.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",

package.json

@@ -1,3 +1,7 @@
-export const UI = ['stoplight', 'swagger', 'redoc']
+export const UI = {
+  STOPLIGHT: 'stoplight',
+  SWAGGER: 'swagger',
+  REDOC: 'redoc',
+}
 export const THEME = ['light', 'dark']
 export const ENABLE_INPUT_EXTS = ['.json', '.yaml', '.yml']

src/constants/index.js

@@ -2,11 +2,9 @@
 import { program } from 'commander'
 import inquirer from 'inquirer'
 import fs from 'fs'
-import yaml from 'js-yaml'
 import ejs from 'ejs'
 import path from 'path'
 import { fileURLToPath } from 'url'
-import $RefParser from '@apidevtools/json-schema-ref-parser'
 import { UI } from './constants/index.js'
 import {
   validateCommandInput,
@@ -16,9 +14,8 @@ import {
   validateInquirerInput,
   validateInquirerOutput,
   isValidUrl,
-  isJSON,
-  isYAML,
 } from './utils/validate.js'
+import { parseOpenApi } from './utils/parser.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -50,7 +47,11 @@ function getCliOptions() {
       'Output HTML file name',
       validateCommandOutput,
     )
-    .option('--ui <ui>', `Choose UI (${UI.join(', ')})`, validateCommandUi)
+    .option(
+      '--ui <ui>',
+      `Choose UI (${Object.values(UI).join(', ')})`,
+      validateCommandUi,
+    )
     .option('--title <title>', 'Title of the HTML page', 'OpenAPI Docs')
     .option('--description <description>', 'Description of the HTML page', '')
     .option(
@@ -68,8 +69,8 @@ async function askQuestions(options) {
       type: 'list',
       name: 'ui',
       message: 'Which UI would you like to use?',
-      default: UI[0],
-      choices: UI,
+      default: UI.STOPLIGHT,
+      choices: Object.values(UI),
       when: !options.ui,
     },
     {
@@ -114,29 +115,15 @@ async function renderOpenApiHtml(result) {
   } else {
     rawApiDocsText = fs.readFileSync(input, 'utf-8')
   }
-
-  let rawApiDocs
-  if (isJSON(rawApiDocsText)) {
-    rawApiDocs = JSON.parse(rawApiDocsText)
-  } else if (isYAML(rawApiDocsText)) {
-    rawApiDocs = yaml.load(rawApiDocsText)
-  } else {
-    throw new Error(
-      'Unsupported file format. Please provide a .json or .yaml/.yml file.',
-    )
-  }
-
-  // resolve $ref pointers
-  // https://github.com/APIDevTools/json-schema-ref-parser/blob/main/docs/ref-parser.md#bundleschema-options-callback
-  const apiDocs = await $RefParser.bundle(rawApiDocs)
+  const apiDocs = await parseOpenApi(rawApiDocsText, ui)
 
   return ejs.render(template, {
     theme: result.theme,
     title: result.title,
     description: result.description,
     jsContent,
     cssContent,
-    apiDocs: JSON.stringify(apiDocs),
+    apiDocs,
   })
 }
 

src/index.js

@@ -0,0 +1,44 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser'
+import stringify from 'safe-stable-stringify'
+import yaml from 'js-yaml'
+import { UI } from '../constants/index.js'
+
+export async function parseOpenApi(rawApiDocsText, ui) {
+  let rawApiDocs
+  if (isJSON(rawApiDocsText)) {
+    rawApiDocs = JSON.parse(rawApiDocsText)
+  } else if (isYAML(rawApiDocsText)) {
+    rawApiDocs = yaml.load(rawApiDocsText)
+  } else {
+    throw new Error(
+      'Unsupported file format. Please provide a .json or .yaml/.yml file.',
+    )
+  }
+  // resolve $ref pointers
+  if (ui === UI.SWAGGER) {
+    // https://github.com/APIDevTools/json-schema-ref-parser/blob/main/docs/ref-parser.md#dereferenceschema-options-callback
+    const apiDocs = await $RefParser.dereference(rawApiDocs)
+    return stringify(apiDocs)
+  }
+  // https://github.com/APIDevTools/json-schema-ref-parser/blob/main/docs/ref-parser.md#bundleschema-options-callback
+  const apiDocs = await $RefParser.bundle(rawApiDocs)
+  return JSON.stringify(apiDocs)
+}
+
+function isJSON(string) {
+  try {
+    JSON.parse(string)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function isYAML(string) {
+  try {
+    yaml.load(string)
+    return true
+  } catch {
+    return false
+  }
+}

src/utils/parser.js

@@ -1,4 +1,3 @@
-import yaml from 'js-yaml'
 import { InvalidArgumentError } from 'commander'
 import { UI, THEME, ENABLE_INPUT_EXTS } from '../constants/index.js'
 
@@ -22,8 +21,8 @@ export function validateCommandOutput(output) {
 }
 
 export function validateCommandUi(ui) {
-  if (!UI.includes(ui)) {
-    const message = `Please choose from: ${UI.join(', ')}.`
+  if (!Object.values(UI).includes(ui)) {
+    const message = `Please choose from: ${Object.values(UI).join(', ')}.`
     throw new InvalidArgumentError(message)
   }
   return ui
@@ -63,24 +62,6 @@ export function isValidUrl(string) {
   }
 }
 
-export function isJSON(string) {
-  try {
-    JSON.parse(string)
-    return true
-  } catch {
-    return false
-  }
-}
-
-export function isYAML(string) {
-  try {
-    yaml.load(string)
-    return true
-  } catch {
-    return false
-  }
-}
-
 function isValidInput(input) {
   if (isValidUrl(input)) {
     return true