Merge branch 'v10-release' into kanad-2024-12-05/v10-migration-guide

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [9.0.4-next.3](https://github.com/readmeio/rdme/compare/v9.0.4-next.2...v9.0.4-next.3) (2024-12-12)
+
+
+### Bug Fixes
+
+* openapi arg doc enhancements, refactors ([#1122](https://github.com/readmeio/rdme/issues/1122)) ([b83b233](https://github.com/readmeio/rdme/commit/b83b23337c09f053bf470bf4b41615353b1f3eae))
+
 ## [9.0.4-next.2](https://github.com/readmeio/rdme/compare/v9.0.4-next.1...v9.0.4-next.2) (2024-12-11)
 
 

documentation/commands/openapi.md

@@ -17,7 +17,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
@@ -54,7 +55,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
@@ -99,7 +101,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)
@@ -139,7 +142,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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "rdme",
-  "version": "9.0.4-next.2",
+  "version": "9.0.4-next.3",
   "description": "ReadMe's official CLI and GitHub Action.",
   "license": "MIT",
   "author": "ReadMe <[email protected]> (https://readme.com)",

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/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.
@@ -28,3 +28,8 @@ export const titleFlag = Flags.string({
 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);
 }