diff --git a/apps/cli/src/command/convert.command.ts b/apps/cli/src/command/convert.command.ts index 65482cc..2649355 100644 --- a/apps/cli/src/command/convert.command.ts +++ b/apps/cli/src/command/convert.command.ts @@ -21,13 +21,14 @@ class BaseConvertCommand extends BaseCommand { super(name); this.option( '-f, --file ', - 'OpenAPI configuration file path', + 'OpenAPI specification file path', ).option('-o, --output ', 'output file path'); } } const OpenAPICommand = new BaseConvertCommand('openapi') - .description('Converting OpenAPI to ADC Configuration') + .description('Convert an OpenAPI specification to equivalent ADC configuration.\n\nLearn more at: https://docs.api7.ai/enterprise/reference/openapi-adc') + .summary('convert OpenAPI spec to ADC configuration') .action(async () => { const opts = OpenAPICommand.optsWithGlobals(); @@ -92,5 +93,6 @@ const OpenAPICommand = new BaseConvertCommand('openapi') }); export const ConvertCommand = new BaseCommand('convert') - .description('Convert other API spec to ADC configurations') + .description('Convert API definitions in other formats to equivalent ADC configuration.') + .summary('convert API definitions in other formats to ADC configuration') .addCommand(OpenAPICommand); diff --git a/apps/cli/src/command/diff.command.ts b/apps/cli/src/command/diff.command.ts index df29312..e9dc0b8 100644 --- a/apps/cli/src/command/diff.command.ts +++ b/apps/cli/src/command/diff.command.ts @@ -158,14 +158,16 @@ export const DiffResourceTask = ( export const DiffCommand = new BackendCommand( 'diff', - 'Show the difference between local and backend configurations', + 'show differences between the local and the backend configurations', + 'Compare the configuration in the specified file(s) with the backend configuration', ) .option( '-f, --file ', - 'The files you want to synchronize, can be set more than one.', + 'file to compare', (filePath, files: Array = []) => files.concat(filePath), ) .addOption(NoLintOption) + .addExample('adc diff -f adc.yaml') .addExample('adc diff -f service-a.yaml -f service-b.yaml') .handle(async (opts) => { const backend = loadBackend(opts.backend, opts); diff --git a/apps/cli/src/command/dump.command.ts b/apps/cli/src/command/dump.command.ts index 0a38b9c..1101a52 100644 --- a/apps/cli/src/command/dump.command.ts +++ b/apps/cli/src/command/dump.command.ts @@ -66,15 +66,16 @@ export const LoadRemoteConfigurationTask = ({ export const DumpCommand = new BackendCommand( 'dump', - 'Dump configurations from the backend', + 'save the configuration of the backend to a file', + 'Save the configuration of the backend to the specified YAML file.', ) .option( '-o, --output ', - 'Specify the file path where data is dumped from the backend', + 'path of the file to save the configuration', 'adc.yaml', ) .addExample('adc dump') - .addExample('adc dump -o other-name.yaml') + .addExample('adc dump -o service-configuration.yaml') .handle(async (opts) => { const backend = loadBackend(opts.backend, opts); const tasks = new Listr( diff --git a/apps/cli/src/command/helper.ts b/apps/cli/src/command/helper.ts index 6213047..db9a544 100644 --- a/apps/cli/src/command/helper.ts +++ b/apps/cli/src/command/helper.ts @@ -10,16 +10,17 @@ import qs from 'qs'; export class BaseCommand extends Command { private exmaples: Array = []; - constructor(name: string, description?: string) { + constructor(name: string, summary?: string, description?: string) { super(name); + if (summary) this.summary(summary); if (description) this.description(description); // Add global flag - verbose this.addOption( new Option( '--verbose ', - 'Override verbose logging levels, it supports 0: no logs, 1: basic logs, 2: debug logs', + 'set the verbosity level for logs (0: no logs, 1: basic logs, 2: debug logs)', ) .argParser((val) => { const int = parseInt(val); @@ -34,7 +35,7 @@ export class BaseCommand extends Command { public addExample(exmaple: string) { if (this.exmaples.length === 0) this.addHelpText('after', () => { - return `\nExample:\n\n${this.exmaples + return `\nExamples:\n\n${this.exmaples .map((example) => ` $ ${example}`) .join('\n')}\n`; }); @@ -45,8 +46,8 @@ export class BaseCommand extends Command { } export class BackendCommand extends BaseCommand { - constructor(name: string, description?: string) { - super(name, description); + constructor(name: string, summary?: string, description?: string) { + super(name, summary, description); this.addBackendOptions(); } @@ -92,7 +93,7 @@ export class BackendCommand extends BaseCommand { }; this.addOption( - new Option('--backend ', 'Type of backend to connect') + new Option('--backend ', 'type of backend to connect to') .env('ADC_BACKEND') .choices(['apisix', 'api7ee']) .default('apisix'), @@ -100,28 +101,28 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--server ', - 'HTTP address of backend. This value can also be set using the environment variable ADC_SERVER environment variable', + 'HTTP address of the backend', ) .env('ADC_SERVER') .default('http://localhost:9180'), ) .addOption( - new Option('--token ', 'Token used to access the backend').env( + new Option('--token ', 'token for ADC to connect to the backend').env( 'ADC_TOKEN', ), ) .addOption( new Option( '--gateway-group ', - 'Gateway group used to specify the gateway group to operate [API7EE backend only]', + 'gateway group to operate on (only supported for "api7ee" backend)', ) .env('ADC_GATEWAY_GROUP') .default('default'), ) .addOption( new Option( - '--label-selector ', - 'Filter for resource labels (e.g., labelKey=labelValue)', + '--label-selector ', + 'filter resources by labels', ).argParser((val, previous: Record = {}) => Object.assign(previous, qs.parse(val, { delimiter: ',' })), ), @@ -129,7 +130,7 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--include-resource-type ', - 'Filter for resource types, contains only the specified type', + 'filter resources that only contains the specified type', ) .conflicts('excludeResourceType') .choices(Object.values(ADCSDK.ResourceType)) @@ -138,7 +139,7 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--exclude-resource-type ', - 'Filter for resource types, not contains only the specified type', + 'filter resources that does not contain the specified type', ) .conflicts('includeResourceType') .choices(Object.values(ADCSDK.ResourceType)) @@ -147,7 +148,7 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--timeout ', - 'Set a request timeout for the client to connect with Backend Admin API (in duration, e.g., 10s, 1h10m)', + 'timeout for adc to connect with the backend (examples: 10s, 1h10m)', ) .default(10000, '10s') .argParser((value) => { @@ -157,7 +158,7 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--ca-cert-file ', - 'Path to CA certificate for verifying the Backend Admin API', + 'path to the CA certificate to verify the backend', ) .env('ADC_CA_CERT_FILE') .argParser((value) => @@ -170,33 +171,33 @@ export class BackendCommand extends BaseCommand { .addOption( new Option( '--tls-client-cert-file ', - 'Path to Mutual TLS client certificate for verifying the Backend Admin API', + 'path to the mutual TLS client certificate to verify the backend', ) .env('ADC_TLS_CLIENT_CERT_FILE') .argParser((value) => processCertificateFile( value, - 'The specified Mutual TLS client certificate file does not exist', + 'The specified mutual TLS client certificate file does not exist', ), ), ) .addOption( new Option( '--tls-client-key-file ', - 'Path to Mutual TLS client key for verifying the Backend Admin API', + 'path to the mutual TLS client key to verify the backend', ) .env('ADC_TLS_CLIENT_KEY_FILE') .argParser((value) => processCertificateFile( value, - 'The specified Mutual TLS client key file does not exist', + 'The specified mutual TLS client key file does not exist', ), ), ) .addOption( new Option( '--tls-skip-verify', - `Disable verification of Backend Admin API TLS certificate`, + `disable the verification of the backend TLS certificate`, ) .env('ADC_TLS_SKIP_VERIFY') .default(false), @@ -204,4 +205,4 @@ export class BackendCommand extends BaseCommand { } } -export const NoLintOption = new Option('--no-lint', 'Disable lint check'); +export const NoLintOption = new Option('--no-lint', 'disable lint check'); diff --git a/apps/cli/src/command/index.ts b/apps/cli/src/command/index.ts index 42b0042..6092d74 100644 --- a/apps/cli/src/command/index.ts +++ b/apps/cli/src/command/index.ts @@ -14,9 +14,10 @@ export const setupCommands = (): Command => { const program = new Command('adc'); program + .description('API Declarative CLI (ADC) is a utility to manage API7 Enterprise and Apache APISIX declaratively.\n\nLearn more at: https://docs.api7.ai/enterprise/reference/adc') .configureHelp({ showGlobalOptions: true }) .passThroughOptions() - .version('0.12.1'); + .version('0.12.1', '-v, --version', 'display ADC version'); program .addCommand(PingCommand) diff --git a/apps/cli/src/command/lint.command.ts b/apps/cli/src/command/lint.command.ts index 6d47b89..dd95e62 100644 --- a/apps/cli/src/command/lint.command.ts +++ b/apps/cli/src/command/lint.command.ts @@ -57,13 +57,15 @@ export const LintTask = (): ListrTask<{ local: ADCSDK.Configuration }> => ({ export const LintCommand = new BaseCommand('lint') .description( - 'Check provided configuration files, local execution only, ensuring inputs meet ADC requirements', + 'Lint the local configuration file(s) to ensure it meets ADC requirements.', ) + .summary('lint the local configuration') .option( - '-f, --file ', - 'The files you want to synchronize, can be set more than one.', + '-f, --file ', + 'file to lint', (filePath, files: Array = []) => files.concat(filePath), ) + .addExample('adc lint -f adc.yaml') .addExample('adc lint -f service-a.yaml -f service-b.yaml') .action(async () => { const opts = LintCommand.optsWithGlobals(); diff --git a/apps/cli/src/command/ping.command.ts b/apps/cli/src/command/ping.command.ts index f747f3e..682fbed 100644 --- a/apps/cli/src/command/ping.command.ts +++ b/apps/cli/src/command/ping.command.ts @@ -8,15 +8,16 @@ type PingOptions = BackendOptions; export const PingCommand = new BackendCommand( 'ping', - 'Verify connectivity with backend', + 'check connectivity with the backend', + 'Check connectivity with the configured backend.', ).handle(async (opts) => { const backend = loadBackend(opts.backend, opts); try { await backend.ping(); - console.log(chalk.green('Connected to backend successfully!')); + console.log(chalk.green(`Connected to the "${opts.backend}" backend successfully!`)); } catch (err) { - console.log(chalk.red(`Unable to connect to the backend, ${err}`)); + console.log(chalk.red(`Unable to connect to the "${opts.backend}" backend. ${err}`)); process.exit(1); } }); diff --git a/apps/cli/src/command/sync.command.ts b/apps/cli/src/command/sync.command.ts index 337bc75..b40edaf 100644 --- a/apps/cli/src/command/sync.command.ts +++ b/apps/cli/src/command/sync.command.ts @@ -19,14 +19,16 @@ type SyncOption = BackendOptions & { export const SyncCommand = new BackendCommand( 'sync', - 'Sync local configurations to backend', + 'sync the local configuration to the backend', + 'Synchronize the configuration from the local file(s) to the backend.', ) .option( '-f, --file ', - 'The files you want to synchronize, can be set more than one.', + 'file to synchronize', (filePath, files: Array = []) => files.concat(filePath), ) .addOption(NoLintOption) + .addExample('adc sync -f adc.yaml') .addExample('adc sync -f service-a.yaml -f service-b.yaml') .handle(async (opts) => { const backend = loadBackend(opts.backend, opts); diff --git a/libs/backend-api7/src/index.ts b/libs/backend-api7/src/index.ts index 1f23d82..aa49fea 100644 --- a/libs/backend-api7/src/index.ts +++ b/libs/backend-api7/src/index.ts @@ -172,7 +172,7 @@ export class BackendAPI7 implements ADCSDK.Backend { const gatewayGroups = resp?.data?.list; if (!gatewayGroups.length) { - throw Error(`Gateway group ${this.gatewayGroup} does not exist`); + throw Error(`Gateway group "${this.gatewayGroup}" does not exist`); } ctx.gatewayGroupId = this.gatewayGroupId = gatewayGroups[0].id; },