Merge pull request #22350 from backstage/openapi-tooling/fix-generate-client

feat(repo-tools): Rework command structure and standardize `openapi generate-client`

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 schema openapi generate <plugin-directory>`. 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.
+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 <clientPackageDirectory>`
 
 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
 
-Run `yarn backstage-repo-tools schema openapi generate-client --input-spec <plugin-directory>/src/schema/openapi.yaml --output-directory <plugin-client-directory>`. `<plugin-directory>` should match the same backend plugin we've been using so far. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is `plugins/<plugin-name>-client`.
+From your current backend plugin directory, run `yarn backstage-repo-tools package schema openapi generate --client-package <plugin-client-directory>`. `<plugin-client-directory>` is a new directory and npm package that you should create. The general pattern is `plugins/<plugin-name>-client` or if you want to co-locate this with your other shared types, use `plugins/<plugin-name>-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,
 
@@ -108,7 +108,7 @@ describe('createRouter', () => {
 + app = wrapInOpenApiTestServer(express().use(router));
 ```
 
-This adds a wrapper around the express server that allows it to reroute traffic for `supertest`. Run `yarn backstage-repo-tools schema openapi init` to create some required config files. Now, when you run `yarn backstage-repo-tools schema openapi test` your schema will now be tested against your test data. Any errors will be reported.
+This adds a wrapper around the express server that allows it to reroute traffic for `supertest`. Run `yarn backstage-repo-tools package schema openapi init` to create some required files. Now, when you run `yarn backstage-repo-tools repo schema openapi test` your schema will now be tested against your test data. Any errors will be reported.
 
 Our command is a small wrapper over [`Optic`](https://github.com/opticdev/optic) which does all of the heavy lifting.
 

docs/openapi/generate-client.md

@@ -4,7 +4,7 @@ title: Generate a client from your OpenAPI spec
 description: Documentation on how to create a client for a given OpenAPI spec
 ---
 
-## How to generate a client with `repo-tools schema openapi generate-client`?
+## How to generate a client with `repo-tools package schema openapi generate client`?
 
 ### Prerequisites
 
@@ -20,7 +20,7 @@ info:
 
 ### Generating your client
 
-1. Run `yarn backstage-repo-tools schema openapi generate-client --input-spec <file> --output-directory <directory>`. This will create a new folder in `<directory>/src/generated` to house the generated content.
+1. Run `yarn backstage-repo-tools schema openapi generate client --output-package <directory>`. This will create a new folder in `<directory>/src/generated` to house the generated content.
 2. You should use the generated files as follows,
 
 - `apis/DefaultApi.client.ts` - this is the client that you should use. It has types for all of the various operations on your API.

docs/openapi/test-case-validation.md

@@ -1,15 +1,15 @@
 ---
 id: test-case-validation
 title: Validate your OpenAPI spec against test data
-description: Documentation on how to use the `schema openapi test` command.
+description: Documentation on how to use the `repo schema openapi test` command.
 ---
 
 ## OpenAPI Validation using Test Cases
 
-This is primarily performed by `backstage-repo-tools schema openapi test`. Any errors found in the generated specs can be either
+This is primarily performed by `backstage-repo-tools repo schema openapi test`. Any errors found in the generated specs can be either
 
 1. Fixed manually, this is usually relevant for request body or response body changes.
-2. Fixed automatically with `backstage-repo-tools schema openapi test --update`.
+2. Fixed automatically with `backstage-repo-tools repo schema openapi test --update`.
 3. Fixing the test case. This can happen where a response is mocked as
 
 ```ts