From b107fdf6090352c2c1715891b0f86e46fec67d0c Mon Sep 17 00:00:00 2001 From: Aramis Date: Wed, 24 Jan 2024 10:40:04 -0500 Subject: [PATCH] rework `generate` to take flags instead of subcommands Signed-off-by: Aramis --- .changeset/lovely-bugs-prove.md | 6 ++-- docs/openapi/01-getting-started.md | 4 +-- packages/repo-tools/cli-report.md | 29 ++-------------- packages/repo-tools/src/commands/index.ts | 34 +++++-------------- .../package/schema/openapi/generate/client.ts | 6 +--- .../package/schema/openapi/generate/index.ts | 34 +++++++++++++++++++ plugins/catalog-backend/package.json | 3 +- plugins/search-backend/package.json | 2 +- plugins/todo-backend/package.json | 2 +- 9 files changed, 55 insertions(+), 65 deletions(-) create mode 100644 packages/repo-tools/src/commands/package/schema/openapi/generate/index.ts diff --git a/.changeset/lovely-bugs-prove.md b/.changeset/lovely-bugs-prove.md index b1cb762e73..de55f329bb 100644 --- a/.changeset/lovely-bugs-prove.md +++ b/.changeset/lovely-bugs-prove.md @@ -6,8 +6,8 @@ The following commands now live under the `package` namespace, -- `schema openapi generate` is now `package schema openapi generate server` -- `schema openapi generate-client` is now `package schema openapi generate client` +- `schema openapi generate` is now `package schema openapi generate --server` +- `schema openapi generate-client` is now `package schema openapi generate --client-package` - `schema openapi init` is now `package schema openapi init` And these commands live under the new `repo` namespace, @@ -16,4 +16,4 @@ And these commands live under the new `repo` namespace, - `schema openapi test` is now `repo schema openapi test` - `schema openapi verify` is now `repo schema openapi verify` -This also reworks the `package schema openapi generate client` to accept only an output directory as the input directory can now be inferred. +The `package schema openapi generate` now supports defining both `--server` and `--client-package` to generate both at once.This update also reworks the `--client-package` flag to accept only an output directory as the input directory can now be inferred. diff --git a/docs/openapi/01-getting-started.md b/docs/openapi/01-getting-started.md index ce04e75107..5b9908756f 100644 --- a/docs/openapi/01-getting-started.md +++ b/docs/openapi/01-getting-started.md @@ -45,7 +45,7 @@ You should create a new folder, `src/schema` in your backend plugin to store you ## Generating a typed express router from a spec -Run `yarn backstage-repo-tools package schema openapi generate server `. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use. +Run `yarn backstage-repo-tools package schema openapi generate --server` from the directory with your plugin. This will create an `openapi.generated.ts` file in the `src/schema` directory that contains the OpenAPI schema as well as a generated express router with types. You should add this command to your `package.json` for future use and you can combine both the server generation and the client generation below like so, `yarn backstage-repo-tools package schema openapi generate --server --client-package ` Use it like so, update your `router.ts` or `createRouter.ts` file with the following content, @@ -63,7 +63,7 @@ export async function createRouter( ## Generating a typed client from a spec -From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate client --output-package `. `` is a new directory and npm package that you should create. The general pattern is `plugins/-client` or if you want to co-locate this with your other shared types, use `plugins/-common`. You should add this command to your `package.json` for future use. +From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate --client-package `. `` is a new directory and npm package that you should create. The general pattern is `plugins/-client` or if you want to co-locate this with your other shared types, use `plugins/-common`. You should add this command to your `package.json` for future use. The generated client will have a directory `src/generated` that exports a `DefaultApiClient` class and all generated types. You can use the client like so, diff --git a/packages/repo-tools/cli-report.md b/packages/repo-tools/cli-report.md index 3a03e25352..7988c479b0 100644 --- a/packages/repo-tools/cli-report.md +++ b/packages/repo-tools/cli-report.md @@ -85,40 +85,17 @@ Options: Commands: init - generate [command] + generate [options] help [command] ``` ### `backstage-repo-tools package schema openapi generate` ``` -Usage: backstage-repo-tools package schema openapi generate [options] [command] [command] - -Options: - -h, --help - -Commands: - server - client [options] - help [command] -``` - -### `backstage-repo-tools package schema openapi generate client` - -``` -Usage: backstage-repo-tools package schema openapi generate client [options] - -Options: - --output-package - -h, --help -``` - -### `backstage-repo-tools package schema openapi generate server` - -``` -Usage: backstage-repo-tools package schema openapi generate server [options] +Usage: backstage-repo-tools package schema openapi generate [options] Options: + --client-package [package] -h, --help ``` diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index 290999687c..1fa37402ce 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -44,35 +44,19 @@ function registerPackageCommand(program: Command) { ), ); - const generateCommand = openApiCommand - .command('generate [command]') - .description( - 'Commands for generating various things from an OpenAPI spec.', - ); - - generateCommand - .command('server') - .description( - 'Generates an express server stub using the OpenAPI schema for typings.', - ) - .action( - lazy(() => - import('./package/schema/openapi/generate/server').then(m => m.command), - ), - ); - - generateCommand - .command('client') - .description( - 'Generates a client that can interact with your backend plugin using types from your OpenAPI schema.', - ) - .requiredOption( - '--output-package ', + openApiCommand + .command('generate') + .option( + '--client-package [package]', 'Top-level path to where the client should be generated, ie packages/catalog-client.', ) + .option('--server') + .description( + 'Command to generate a client and/or a server stub from an OpenAPI spec.', + ) .action( lazy(() => - import('./package/schema/openapi/generate/client').then(m => m.command), + import('./package/schema/openapi/generate').then(m => m.command), ), ); } diff --git a/packages/repo-tools/src/commands/package/schema/openapi/generate/client.ts b/packages/repo-tools/src/commands/package/schema/openapi/generate/client.ts index 101c2c918b..5dfed05f93 100644 --- a/packages/repo-tools/src/commands/package/schema/openapi/generate/client.ts +++ b/packages/repo-tools/src/commands/package/schema/openapi/generate/client.ts @@ -87,11 +87,7 @@ async function generate(outputDirectory: string) { }); } -export async function command({ - outputPackage, -}: { - outputPackage: string; -}): Promise { +export async function command(outputPackage: string): Promise { try { await generate(outputPackage); console.log( diff --git a/packages/repo-tools/src/commands/package/schema/openapi/generate/index.ts b/packages/repo-tools/src/commands/package/schema/openapi/generate/index.ts new file mode 100644 index 0000000000..1e48fe3825 --- /dev/null +++ b/packages/repo-tools/src/commands/package/schema/openapi/generate/index.ts @@ -0,0 +1,34 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import chalk from 'chalk'; +import { OptionValues } from 'commander'; +import { command as generateClient } from './client'; +import { command as generateServer } from './server'; + +export async function command(opts: OptionValues) { + if (!opts.clientPackage && !opts.server) { + console.log( + chalk.red('Either --client-package or --server must be defined.'), + ); + process.exit(1); + } + if (opts.clientPackage) { + await generateClient(opts.clientPackage); + } + if (opts.server) { + await generateServer(); + } +} diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json index eee268736a..5e1d4f4e60 100644 --- a/plugins/catalog-backend/package.json +++ b/plugins/catalog-backend/package.json @@ -43,8 +43,7 @@ "prepack": "backstage-cli package prepack", "postpack": "backstage-cli package postpack", "clean": "backstage-cli package clean", - "generate-server": "backstage-repo-tools package schema openapi generate server", - "generate-client": "backstage-repo-tools package schema openapi generate client --output-package packages/catalog-client" + "generate": "backstage-repo-tools package schema openapi generate --server --client-package packages/catalog-client" }, "dependencies": { "@backstage/backend-common": "workspace:^", diff --git a/plugins/search-backend/package.json b/plugins/search-backend/package.json index b328083246..c68f2b816e 100644 --- a/plugins/search-backend/package.json +++ b/plugins/search-backend/package.json @@ -40,7 +40,7 @@ "prepack": "backstage-cli package prepack", "postpack": "backstage-cli package postpack", "clean": "backstage-cli package clean", - "generate-server": "backstage-repo-tools package schema openapi generate server" + "generate": "backstage-repo-tools package schema openapi generate --server" }, "dependencies": { "@backstage/backend-common": "workspace:^", diff --git a/plugins/todo-backend/package.json b/plugins/todo-backend/package.json index 75a070e284..2d9eb469d1 100644 --- a/plugins/todo-backend/package.json +++ b/plugins/todo-backend/package.json @@ -27,7 +27,7 @@ "postpack": "backstage-cli package postpack", "clean": "backstage-cli package clean", "start": "backstage-cli package start", - "generate-server": "backstage-repo-tools package schema openapi generate server" + "generate": "backstage-repo-tools package schema openapi generate --server" }, "dependencies": { "@backstage/backend-common": "workspace:^",