fix: openapi:refs touch ups

__tests__/commands/openapi/refs.test.ts

@@ -7,7 +7,7 @@ import { describe, beforeAll, beforeEach, afterEach, it, expect, vi } from 'vite
 import Command from '../../../src/commands/openapi/refs.js';
 import { runCommandAndReturnResult } from '../../helpers/oclif.js';
 
-describe('openapi:solving-circularity-recursiveness', () => {
+describe('openapi refs', () => {
   let run: (args?: string[]) => Promise<string>;
 
   beforeAll(() => {
@@ -97,4 +97,14 @@ describe('openapi:solving-circularity-recursiveness', () => {
       expect(processedOutput).toStrictEqual(expectedOutput);
     });
   });
+
+  describe('error handling', () => {
+    it.each([['json'], ['yaml']])('should fail if given a Swagger 2.0 definition (format: %s)', async format => {
+      const spec = require.resolve(`@readme/oas-examples/2.0/${format}/petstore.${format}`);
+
+      await expect(run([spec])).rejects.toStrictEqual(
+        new Error('Sorry, this ref resolver feature in rdme only supports OpenAPI 3.0+ definitions.'),
+      );
+    });
+  });
 });

documentation/commands/openapi.md

@@ -245,12 +245,12 @@ FLAGS
 DESCRIPTION
   Resolves circular and recursive references in OpenAPI by replacing them with object schemas.
 
-  This command addresses limitations in ReadMe’s support for circular or recursive references within OpenAPI
-  specifications. It automatically identifies and replaces these references with simplified object schemas, ensuring
-  compatibility for seamless display in the ReadMe platform. As a result, instead of displaying an empty form, as would
-  occur with schemas containing such references, you will receive a flattened representation of the object, showing what
-  the object can potentially contain, including references to itself. Complex circular references may require manual
-  inspection and may not be fully resolved.
+  This command provides a workaround for circular or recursive references within OpenAPI definitions so they can render
+  properly in ReadMe. It automatically identifies and replaces these references with simplified object schemas, ensuring
+  compatibility for seamless display in the ReadMe API Reference. As a result, instead of displaying an empty form, as
+  would occur with schemas containing such references, you will receive a flattened representation of the object,
+  showing what the object can potentially contain, including references to itself. Complex circular references may
+  require manual inspection and may not be fully resolved.
 
 EXAMPLES
   This will resolve circular and recursive references in the OpenAPI definition at the given file or URL:
@@ -264,7 +264,7 @@ EXAMPLES
 
   If you wish to automate this command, you can pass in CLI arguments to bypass the prompts:
 
-    $ rdme openapi:refs petstore.json -out petstore.openapi.json
+    $ rdme openapi:refs petstore.json --out petstore.openapi.json
 ```
 
 ## `rdme openapi:validate [SPEC]`

src/commands/openapi/refs.ts

@@ -7,12 +7,13 @@
 
 import { Args, Flags } from '@oclif/core';
 import chalk from 'chalk';
+import ora from 'ora';
 import prompts from 'prompts';
 
 import analyzeOas from '../../lib/analyzeOas.js';
 import BaseCommand from '../../lib/baseCommand.js';
 import { workingDirectoryFlag } from '../../lib/flags.js';
-import { info, warn, debug } from '../../lib/logger.js';
+import { info, warn, debug, oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
 import { validateFilePath } from '../../lib/validatePromptInput.js';
@@ -23,7 +24,7 @@
   static summary = 'Resolves circular and recursive references in OpenAPI by replacing them with object schemas.';
 
   static description =
-    'This command addresses limitations in ReadMe’s support for circular or recursive references within OpenAPI specifications. It automatically identifies and replaces these references with simplified object schemas, ensuring compatibility for seamless display in the ReadMe platform. As a result, instead of displaying an empty form, as would occur with schemas containing such references, you will receive a flattened representation of the object, showing what the object can potentially contain, including references to itself. Complex circular references may require manual inspection and may not be fully resolved.';
+    'This command provides a workaround for circular or recursive references within OpenAPI definitions so they can render properly in ReadMe. It automatically identifies and replaces these references with simplified object schemas, ensuring compatibility for seamless display in the ReadMe API Reference. As a result, instead of displaying an empty form, as would occur with schemas containing such references, you will receive a flattened representation of the object, showing what the object can potentially contain, including references to itself. Complex circular references may require manual inspection and may not be fully resolved.';
 
   static args = {
     spec: Args.string({ description: 'A file/URL to your API definition' }),
@@ -311,13 +312,22 @@
       this.debug(`Switching working directory from ${previousWorkingDirectory} to ${process.cwd()}`);
     }
 
-    const { preparedSpec, specPath } = await prepareOas(spec, 'openapi:refs', { convertToLatest: true });
-    const openApiData = JSON.parse(preparedSpec);
+    const { preparedSpec, specPath, specType } = await prepareOas(spec, 'openapi:refs', { convertToLatest: true });
+    if (specType !== 'OpenAPI') {
+      throw new Error('Sorry, this ref resolver feature in rdme only supports OpenAPI 3.0+ definitions.');
+    }
+
+    const openApiData: OASDocument = JSON.parse(preparedSpec);
+
+    const spinner = ora({ ...oraOptions() });
+    spinner.start('Identifying and resolving circular/recursive references in your API definition...');
 
     try {
       await OpenAPIRefsCommand.resolveCircularRefs(openApiData, openApiData.components!.schemas!);
+      spinner.succeed(`${spinner.text} done! ✅`);
     } catch (err) {
       this.debug(`${err.message}`);
+      spinner.fail();
       throw err;
     }
 
@@ -335,7 +345,6 @@
     const outputPath = promptResults.outputPath;
     this.debug(`Saving processed spec to ${outputPath}...`);
     fs.writeFileSync(outputPath, JSON.stringify(openApiData, null, 2));
-    this.debug('Processed spec saved successfully.');
 
     return Promise.resolve(chalk.green(`Your API definition has been processed and saved to ${outputPath}!`));
   }