diff --git a/.changeset/brown-meals-trade.md b/.changeset/brown-meals-trade.md new file mode 100644 index 0000000000..f6849fa19b --- /dev/null +++ b/.changeset/brown-meals-trade.md @@ -0,0 +1,5 @@ +--- +'@backstage/repo-tools': minor +--- + +**BREAKING**: The OpenAPI commands are now found within the `schema openapi` sub-command. For example `yarn backstage-repo-tools schema:openapi:verify` is now `yarn backstage-repo-tools schema openapi verify`. diff --git a/.changeset/swift-students-type.md b/.changeset/swift-students-type.md new file mode 100644 index 0000000000..577fbeb8b6 --- /dev/null +++ b/.changeset/swift-students-type.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-openapi-utils': patch +--- + +Updated README to reflect changes in `@backstage/repo-tools`. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 86ac320ac7..ec0a791dcb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -96,7 +96,7 @@ jobs: run: node scripts/verify-api-reference.js - name: verify openapi yaml file matches generated ts file - run: yarn backstage-repo-tools schema:openapi:verify + run: yarn backstage-repo-tools schema openapi verify - name: verify doc links run: node scripts/verify-links.js diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md index 122dca0201..ba286f94e8 100644 --- a/packages/backend-openapi-utils/README.md +++ b/packages/backend-openapi-utils/README.md @@ -8,7 +8,7 @@ This package is meant to provide a typed Express router for an OpenAPI spec. Bas ### Configuration -1. Run `yarn --cwd backstage-cli package schema:openapi:generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.generated.ts`. The command will try to execute both a lint and prettier step on the generated file, where applicable. +1. Run `yarn --cwd backstage-cli package schema openapi generate` to translate your `src/schema/openapi.yaml` to a new Typescript file in `src/schema/openapi.generated.ts`. The command will try to execute both a lint and prettier step on the generated file, where applicable. 2. In your plugin's `src/service/createRouter.ts`, diff --git a/packages/repo-tools/cli-report.md b/packages/repo-tools/cli-report.md index b361bac02f..789b4bc407 100644 --- a/packages/repo-tools/cli-report.md +++ b/packages/repo-tools/cli-report.md @@ -14,8 +14,7 @@ Options: Commands: api-reports [options] [paths...] type-deps - schema:openapi:verify [paths...] - schema:openapi:generate [paths...] + schema [command] help [command] ``` @@ -37,19 +36,46 @@ Options: -h, --help ``` -### `backstage-repo-tools schema:openapi:generate` +### `backstage-repo-tools schema` ``` -Usage: backstage-repo-tools schema:openapi:generate [options] [paths...] +Usage: backstage-repo-tools schema [options] [command] [command] + +Options: + -h, --help + +Commands: + openapi [command] + help [command] +``` + +### `backstage-repo-tools schema openapi` + +``` +Usage: backstage-repo-tools schema openapi [options] [command] [command] + +Options: + -h, --help + +Commands: + verify [paths...] + generate [paths...] + help [command] +``` + +### `backstage-repo-tools schema openapi generate` + +``` +Usage: backstage-repo-tools schema openapi generate [options] [paths...] Options: -h, --help ``` -### `backstage-repo-tools schema:openapi:verify` +### `backstage-repo-tools schema openapi verify` ``` -Usage: backstage-repo-tools schema:openapi:verify [options] [paths...] +Usage: backstage-repo-tools schema openapi verify [options] [paths...] Options: -h, --help diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index f4d02df3bc..a8324c7d33 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -18,6 +18,30 @@ import { assertError } from '@backstage/errors'; import { Command } from 'commander'; import { exitWithError } from '../lib/errors'; +function registerSchemaCommand(program: Command) { + const command = program + .command('schema [command]') + .description('Various tools for working with API schema'); + + const openApiCommand = command + .command('openapi [command]') + .description('Tooling for OpenApi schema'); + + openApiCommand + .command('verify [paths...]') + .description( + 'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.generated.ts` file.', + ) + .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand))); + + openApiCommand + .command('generate [paths...]') + .description( + 'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.', + ) + .action(lazy(() => import('./openapi/generate').then(m => m.bulkCommand))); +} + export function registerCommands(program: Command) { program .command('api-reports [paths...]') @@ -63,19 +87,7 @@ export function registerCommands(program: Command) { .description('Find inconsistencies in types of all packages and plugins') .action(lazy(() => import('./type-deps/type-deps').then(m => m.default))); - program - .command('schema:openapi:verify [paths...]') - .description( - 'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.generated.ts` file.', - ) - .action(lazy(() => import('./openapi/verify').then(m => m.bulkCommand))); - - program - .command('schema:openapi:generate [paths...]') - .description( - 'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.', - ) - .action(lazy(() => import('./openapi/generate').then(m => m.bulkCommand))); + registerSchemaCommand(program); } // Wraps an action function so that it always exits and handles errors diff --git a/packages/repo-tools/src/commands/openapi/verify.ts b/packages/repo-tools/src/commands/openapi/verify.ts index f6dda66738..4c4f310f73 100644 --- a/packages/repo-tools/src/commands/openapi/verify.ts +++ b/packages/repo-tools/src/commands/openapi/verify.ts @@ -47,7 +47,7 @@ async function verify(directoryPath: string) { if (!isEqual(schema.default, yaml)) { const path = relativePath(cliPaths.targetRoot, directoryPath); throw new Error( - `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn backstage-repo-tools schema:openapi:generate ${path}\` to regenerate \`${TS_SCHEMA_PATH}\`.`, + `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn backstage-repo-tools schema openapi generate ${path}\` to regenerate \`${TS_SCHEMA_PATH}\`.`, ); } }