repo-tools: switch to using sub commands

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.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`.

.changeset/swift-students-type.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-openapi-utils': patch
+---
+
+Updated README to reflect changes in `@backstage/repo-tools`.

.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

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 <package-dir> 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 <package-dir> 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`,
 

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

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

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}\`.`,
     );
   }
 }