docs: consolidate description of spec arg

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

@@ -11,7 +11,7 @@ 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/upload.ts

@@ -1,30 +1,26 @@
 import fs from 'node:fs';
 import nodePath from 'node:path';
 
-import { Args, Flags } from '@oclif/core';
+import { Flags } from '@oclif/core';
 import ora from 'ora';
 import prompts from 'prompts';
 import slugify from 'slugify';
 import { file as tmpFile } from 'tmp-promise';
 
 import BaseCommand from '../../lib/baseCommand.js';
-import { keyFlag } from '../../lib/flags.js';
+import { keyFlag, specArg } from '../../lib/flags.js';
 import isCI, { isTest } from '../../lib/isCI.js';
 import { oraOptions } from '../../lib/logger.js';
 import prepareOas from '../../lib/prepareOas.js';
 import promptTerminal from '../../lib/promptWrapper.js';
 
 export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUploadCommand> {
+  static description = 'Upload (or reupload) your API definition to ReadMe.';
+
   static args = {
-    spec: Args.string({
-      summary: 'A file/URL to your API definition',
-      description:
-        'If your working directory and all subdirectories contain a single OpenAPI file, you can omit the file name.',
-    }),
+    spec: specArg,
   };
 
-  static description = 'the new openapi command yayay';
-
   static flags = {
     key: keyFlag,
     uri: Flags.string({
@@ -48,11 +44,6 @@ export default class OpenAPIUploadCommand extends BaseCommand<typeof OpenAPIUplo
       description: 'You can pass in a file name like so:',
       command: '<%= config.bin %> <%= command.id %> --version=1.0.0 openapi.json',
     },
-    {
-      description:
-        'If your working directory and all subdirectories contain a single OpenAPI file, you can omit the file name:',
-      command: '<%= config.bin %> <%= command.id %> --version=1.0.0',
-    },
     {
       description:
         'You can also pass in a file in a subdirectory (we recommend always running the CLI from the root of your repository):',

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,9 @@ export const titleFlag = Flags.string({
 export const workingDirectoryFlag = Flags.string({
   description: 'Working directory (for usage with relative external references)',
 });
+
+export const specArg = Args.string({
+  summary: 'A path to your API definition',
+  description:
+    'This can be 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.',
+});