fix: openapi arg doc enhancements, refactors (#1122)

## 🧰 Changes

cherry picks a few refactors from
#1116 to minimize that diff and
bring these changes to the v9 channel

## 🧬 QA & Testing

do tests still pass?

documentation/commands/openapi.md

@@ -19,7 +19,8 @@ USAGE
     [--workingDirectory <value>] [--github] [--dryRun] [--useSpecVersion] [--raw] [--create | --update]
 
 ARGUMENTS
-  SPEC  A file/URL to your API definition
+  SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
+        subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --create                    Bypasses the create/update prompt and creates a new API definition in ReadMe.
@@ -121,7 +122,8 @@ USAGE
   $ rdme openapi convert [SPEC] [--out <value>] [--title <value>] [--workingDirectory <value>]
 
 ARGUMENTS
-  SPEC  A file/URL to your API definition
+  SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
+        subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --out=<value>               Output file path to write converted file to
@@ -158,7 +160,8 @@ USAGE
     dme...] [--workingDirectory <value>]
 
 ARGUMENTS
-  SPEC  A file/URL to your API definition
+  SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
+        subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --feature=<option>...       A specific OpenAPI or ReadMe feature you wish to see detailed information on (if it
@@ -203,7 +206,8 @@ USAGE
     <value>] [--workingDirectory <value>]
 
 ARGUMENTS
-  SPEC  A file/URL to your API definition
+  SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
+        subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --method=<value>...         Methods to reduce by (can only be used alongside the `path` option)
@@ -243,7 +247,8 @@ USAGE
   $ rdme openapi validate [SPEC] [--github] [--workingDirectory <value>]
 
 ARGUMENTS
-  SPEC  A file/URL to your API definition
+  SPEC  A path to your API definition — either a local file path or a URL. If your working directory and all
+        subdirectories contain a single OpenAPI file, you can omit the path.
 
 FLAGS
   --github                    Create a new GitHub Actions workflow for this command.

src/commands/openapi/convert.ts

@@ -3,12 +3,12 @@ import type { OASDocument } from 'oas/types';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { Args, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import prompts from 'prompts';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
+import { specArg, titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
 import { warn } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
@@ -21,7 +21,7 @@ export default class OpenAPIConvertCommand extends BaseCommand<typeof OpenAPICon
     'Converts Swagger files and Postman collections to OpenAPI and bundles any external references. **Note**: All of our other OpenAPI commands already do this conversion automatically, but this command is available in case you need this functionality exclusively.';
 
   static args = {
-    spec: Args.string({ description: 'A file/URL to your API definition' }),
+    spec: specArg,
   };
 
   static flags = {

src/commands/openapi/index.ts

@@ -1,12 +1,12 @@
 import type { OpenAPIPromptOptions } from '../../lib/prompts.js';
 
-import { Args, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import ora from 'ora';
 import parse from 'parse-link-header';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { githubFlag, keyFlag, titleFlag, versionFlag, workingDirectoryFlag } from '../../lib/flags.js';
+import { githubFlag, keyFlag, specArg, titleFlag, versionFlag, workingDirectoryFlag } from '../../lib/flags.js';
 import { info, oraOptions, warn } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import * as promptHandler from '../../lib/prompts.js';
@@ -31,7 +31,7 @@ export default class OpenAPICommand extends BaseCommand<typeof OpenAPICommand> {
   };
 
   static args = {
-    spec: Args.string({ description: 'A file/URL to your API definition' }),
+    spec: specArg,
   };
 
   static flags = {

src/commands/openapi/inspect.ts

@@ -1,15 +1,15 @@
 import type { Analysis, AnalyzedFeature } from '../../lib/analyzeOas.js';
 import type { OASDocument } from 'oas/types';
 
-import { Args, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import ora from 'ora';
 import pluralize from 'pluralize';
 import { getBorderCharacters, table } from 'table';
 
 import analyzeOas, { getSupportedFeatures } from '../../lib/analyzeOas.js';
 import BaseCommand from '../../lib/baseCommand.js';
-import { workingDirectoryFlag } from '../../lib/flags.js';
+import { specArg, workingDirectoryFlag } from '../../lib/flags.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import SoftError from '../../lib/softError.js';
@@ -178,7 +178,7 @@ export default class OpenAPIInspectCommand extends BaseCommand<typeof OpenAPIIns
     "This command will perform a comprehensive analysis of your API definition to determine how it's utilizing aspects of the OpenAPI Specification (such as circular references, polymorphism, etc.) and any ReadMe-specific extensions you might be using.";
 
   static args = {
-    spec: Args.string({ description: 'A file/URL to your API definition' }),
+    spec: specArg,
   };
 
   static flags = {

src/commands/openapi/reduce.ts

@@ -3,15 +3,15 @@ import type { OASDocument } from 'oas/types';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { Args, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import Oas from 'oas';
 import oasReducer from 'oas/reducer';
 import ora from 'ora';
 import prompts from 'prompts';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
+import { specArg, titleFlag, workingDirectoryFlag } from '../../lib/flags.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
@@ -24,7 +24,7 @@ export default class OpenAPIReduceCommand extends BaseCommand<typeof OpenAPIRedu
     "Reduce your API definition down to a specific set of tags or paths, which can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.";
 
   static args = {
-    spec: Args.string({ description: 'A file/URL to your API definition' }),
+    spec: specArg,
   };
 
   static flags = {

src/commands/openapi/validate.ts

@@ -1,8 +1,7 @@
-import { Args } from '@oclif/core';
 import chalk from 'chalk';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { githubFlag, workingDirectoryFlag } from '../../lib/flags.js';
+import { githubFlag, specArg, workingDirectoryFlag } from '../../lib/flags.js';
 import prepareOas from '../../lib/prepareOas.js';
 
 export default class OpenAPIValidateCommand extends BaseCommand<typeof OpenAPIValidateCommand> {
@@ -15,7 +14,7 @@ export default class OpenAPIValidateCommand extends BaseCommand<typeof OpenAPIVa
   static id = 'openapi validate' as const;
 
   static args = {
-    spec: Args.string({ description: 'A file/URL to your API definition' }),
+    spec: specArg,
   };
 
   static examples = [

src/lib/flags.ts

@@ -1,4 +1,4 @@
-import { Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 
 /**
  * Used in any command where `github` is a `flag.
@@ -62,3 +62,8 @@ export const baseVersionFlags = {
 export const workingDirectoryFlag = Flags.string({
   description: 'Working directory (for usage with relative external references)',
 });
+
+export const specArg = Args.string({
+  description:
+    'A path to your API definition — either a local file path or a URL. If your working directory and all subdirectories contain a single OpenAPI file, you can omit the path.',
+});

src/lib/logger.ts

@@ -55,8 +55,7 @@ function info(
 }
 
 function oraOptions() {
-  // Disables spinner in tests so it doesn't pollute test output
-  const opts: Writable<OraOptions> = { isSilent: isTest() };
+  const opts: Writable<OraOptions> = {};
 
   // Cleans up ora output so it prints nicely alongside debug logs
   /* istanbul ignore next */

src/lib/readmeAPIFetch.ts

@@ -244,6 +244,23 @@ export async function handleAPIv1Res(res: Response, rejectOnJsonError = true) {
   return Promise.reject(body);
 }
 
+/**
+ * If you supply `undefined` or `null` to the `Headers` API,
+ * it'll convert those to a string by default,
+ * so we instead filter those out here.
+ */
+function filterOutFalsyHeaders(inputHeaders: Headers) {
+  const headers = new Headers();
+
+  for (const header of inputHeaders.entries()) {
+    if (header[1] !== 'null' && header[1] !== 'undefined' && header[1].length > 0) {
+      headers.set(header[0], header[1]);
+    }
+  }
+
+  return headers;
+}
+
 /**
  * Returns the basic auth header and any other defined headers for use in `fetch` calls against ReadMe API v1.
  *
@@ -252,24 +269,14 @@ export function cleanAPIv1Headers(
   key: string,
   /** used for `x-readme-header` */
   version?: string,
-  inputHeaders: Headers = new Headers(),
+  headers: Headers = new Headers(),
 ) {
   const encodedKey = Buffer.from(`${key}:`).toString('base64');
-  const headers = new Headers({
-    Authorization: `Basic ${encodedKey}`,
-  });
+  headers.set('Authorization', `Basic ${encodedKey}`);
 
   if (version) {
     headers.set('x-readme-version', version);
   }
 
-  for (const header of inputHeaders.entries()) {
-    // If you supply `undefined` or `null` to the `Headers` API it'll convert those to a string by default,
-    // so we instead filter those out here.
-    if (header[1] !== 'null' && header[1] !== 'undefined' && header[1].length > 0) {
-      headers.set(header[0], header[1]);
-    }
-  }
-
-  return headers;
+  return filterOutFalsyHeaders(headers);
 }