diff --git a/documentation/commands/openapi.md b/documentation/commands/openapi.md index 44a45a48b..a7cc44c27 100644 --- a/documentation/commands/openapi.md +++ b/documentation/commands/openapi.md @@ -143,7 +143,7 @@ Resolves circular and recursive references in OpenAPI by replacing them with obj ``` USAGE - $ rdme openapi resolve [SPEC] [--out ] [--workingDirectory ] + $ rdme openapi resolve [SPEC] [--out ] [--title ] [--workingDirectory ] ARGUMENTS SPEC A path to your API definition — either a local file path or a URL. If your working directory and all @@ -151,6 +151,7 @@ ARGUMENTS FLAGS --out= Output file path to write resolved file to + --title= An override value for the `info.title` field in the API definition --workingDirectory= Working directory (for usage with relative external references) DESCRIPTION @@ -184,7 +185,7 @@ Upload (or re-upload) your API definition to ReadMe. ``` USAGE - $ rdme openapi upload [SPEC] --key [--slug ] [--useSpecVersion | --branch ] + $ rdme openapi upload [SPEC] --key [--slug ] [--title ] [--useSpecVersion | --branch ] ARGUMENTS SPEC A path to your API definition — either a local file path or a URL. If your working directory and all @@ -194,6 +195,7 @@ FLAGS --key= (required) ReadMe project API key --branch= [default: stable] ReadMe project version --slug= Override the slug (i.e., the unique identifier) for your API definition. + --title= An override value for the `info.title` field in the API definition --useSpecVersion Use the OpenAPI `info.version` field for your ReadMe project version DESCRIPTION diff --git a/src/commands/openapi/convert.ts b/src/commands/openapi/convert.ts index a8134cd73..dd4c20a7a 100644 --- a/src/commands/openapi/convert.ts +++ b/src/commands/openapi/convert.ts @@ -14,6 +14,8 @@ import promptTerminal from '../../lib/promptWrapper.js'; import { validateFilePath } from '../../lib/validatePromptInput.js'; export default class OpenAPIConvertCommand extends BaseCommand { + id = 'openapi convert' as const; + static summary = 'Converts an API definition to OpenAPI and bundles any external references.'; static description = @@ -43,8 +45,7 @@ export default class OpenAPIConvertCommand extends BaseCommand { + id = 'openapi inspect' as const; + static summary = 'Analyze an OpenAPI/Swagger definition for various OpenAPI and ReadMe feature usage.'; static description = @@ -251,7 +253,7 @@ export default class OpenAPIInspectCommand extends BaseCommand { + id = 'openapi reduce' as const; + static summary = 'Reduce an OpenAPI definition into a smaller subset.'; static description = @@ -58,9 +60,8 @@ export default class OpenAPIReduceCommand extends BaseCommand; export default class OpenAPIResolveCommand extends BaseCommand { + id = 'openapi resolve' as const; + static summary = 'Resolves circular and recursive references in OpenAPI by replacing them with object schemas.'; static description = @@ -50,6 +52,7 @@ export default class OpenAPIResolveCommand extends BaseCommand { + id = 'openapi upload' as const; + static summary = 'Upload (or re-upload) your API definition to ReadMe.'; static description = [ @@ -56,6 +58,7 @@ export default class OpenAPIUploadCommand extends BaseCommand { + id = 'openapi validate' as const; + static summary = 'Validate your OpenAPI/Swagger definition.'; static description = @@ -41,7 +43,7 @@ export default class OpenAPIValidateCommand extends BaseCommand extends // protected property in the base oclif class declare debug: (...args: unknown[]) => void; - protected info(input: Parameters[0], opts: Parameters[1]): void { + public info(input: Parameters[0], opts?: Parameters[1]): void { if (!this.jsonEnabled()) { info(input, opts); } diff --git a/src/lib/prepareOas.ts b/src/lib/prepareOas.ts index f8d384d31..b5f02aecf 100644 --- a/src/lib/prepareOas.ts +++ b/src/lib/prepareOas.ts @@ -1,5 +1,5 @@ import type { OpenAPI } from 'openapi-types'; -import type { CommandIdForTopic } from '../index.js'; +import type { CommandIdForTopic, OpenAPICommands } from '../index.js'; import chalk from 'chalk'; import OASNormalize from 'oas-normalize'; @@ -7,7 +7,7 @@ import { getAPIDefinitionType } from 'oas-normalize/lib/utils'; import ora from 'ora'; import isCI from './isCI.js'; -import { debug, info, oraOptions } from './logger.js'; +import { oraOptions } from './logger.js'; import promptTerminal from './promptWrapper.js'; import readdirRecursive from './readdirRecursive.js'; @@ -49,26 +49,9 @@ function capitalizeSpecType { - debug(`attempting to oas-normalize ${file}`); + this.debug(`attempting to oas-normalize ${file}`); const oas = new OASNormalize(file, { enablePaths: true }); return oas .version() .then(({ specification, version }) => { - debug(`specification type for ${file}: ${specification}`); - debug(`version for ${file}: ${version}`); + this.debug(`specification type for ${file}: ${specification}`); + this.debug(`version for ${file}: ${version}`); return ['openapi', 'swagger', 'postman'].includes(specification) ? { filePath: file, specType: capitalizeSpecType(specification) as SpecType, version } : null; }) .catch(e => { - debug(`error extracting API definition specification version for ${file}: ${e.message}`); + this.debug(`error extracting API definition specification version for ${file}: ${e.message}`); return null; }); }), ) ).filter(truthy); - debug(`number of possible OpenAPI/Swagger files found: ${possibleSpecFiles.length}`); + this.debug(`number of possible OpenAPI/Swagger files found: ${possibleSpecFiles.length}`); if (!possibleSpecFiles.length) { fileFindingSpinner.fail(); @@ -134,7 +117,7 @@ export default async function prepareOas( if (possibleSpecFiles.length === 1) { fileFindingSpinner.stop(); - info(chalk.yellow(`We found ${specPath} and are attempting to ${action} it.`)); + this.info(chalk.yellow(`We found ${specPath} and are attempting to ${action} it.`)); } else if (possibleSpecFiles.length > 1) { if (isCI()) { fileFindingSpinner.fail(); @@ -160,9 +143,9 @@ export default async function prepareOas( const spinner = ora({ text: `Validating the API definition located at ${specPath}...`, ...oraOptions() }).start(); - debug(`about to normalize spec located at ${specPath}`); + this.debug(`about to normalize spec located at ${specPath}`); const oas = new OASNormalize(specPath, { colorizeErrors: true, enablePaths: true }); - debug('spec normalized'); + this.debug('spec normalized'); // We're retrieving the original specification type here instead of after validation because if // they give us a Postman collection we should tell them that we handled a Postman collection, not @@ -182,42 +165,42 @@ export default async function prepareOas( }) .catch((err: Error) => { spinner.fail(); - debug(`raw oas load error object: ${JSON.stringify(err)}`); + this.debug(`raw oas load error object: ${JSON.stringify(err)}`); throw err; }); let api: OpenAPI.Document; await oas.validate().catch((err: Error) => { spinner.fail(); - debug(`raw validation error object: ${JSON.stringify(err)}`); + this.debug(`raw validation error object: ${JSON.stringify(err)}`); throw err; }); // If we were supplied a Postman collection this will **always** convert it to OpenAPI 3.0. - debug('converting the spec to OpenAPI 3.0 (if necessary)'); + this.debug('converting the spec to OpenAPI 3.0 (if necessary)'); api = await oas.convert().catch((err: Error) => { spinner.fail(); - debug(`raw openapi conversion error object: ${JSON.stringify(err)}`); + this.debug(`raw openapi conversion error object: ${JSON.stringify(err)}`); throw err; }); spinner.stop(); - debug('👇👇👇👇👇 spec validated! logging spec below 👇👇👇👇👇'); - debug(api); - debug('👆👆👆👆👆 finished logging spec 👆👆👆👆👆'); - debug(`spec type: ${specType}`); + this.debug('👇👇👇👇👇 spec validated! logging spec below 👇👇👇👇👇'); + this.debug(api); + this.debug('👆👆👆👆👆 finished logging spec 👆👆👆👆👆'); + this.debug(`spec type: ${specType}`); - if (opts.title) { - debug(`renaming title field to ${opts.title}`); - api.info.title = opts.title; + if (this.flags.title) { + this.debug(`renaming title field to ${this.flags.title}`); + api.info.title = this.flags.title; } const specFileType = oas.type; // No need to optional chain here since `info.version` is required to pass validation const specVersion: string = api.info.version; - debug(`version in spec: ${specVersion}`); + this.debug(`version in spec: ${specVersion}`); const commandsThatBundle: (typeof command)[] = [ 'openapi inspect', @@ -229,7 +212,7 @@ export default async function prepareOas( if (commandsThatBundle.includes(command)) { api = await oas.bundle(); - debug('spec bundled'); + this.debug('spec bundled'); } return {