From e16864039b7653813baeff5f279dbd28c1390cc6 Mon Sep 17 00:00:00 2001 From: Aramis Date: Thu, 18 Jan 2024 18:18:47 -0500 Subject: [PATCH] fix more documentation and workflows Signed-off-by: Aramis --- .changeset/lovely-bugs-prove.md | 2 +- .github/workflows/ci.yml | 6 +- docs/openapi/generate-client.md | 4 +- docs/openapi/test-case-validation.md | 6 +- packages/repo-tools/cli-report.md | 138 +++++++++++++++++++++------ 5 files changed, 116 insertions(+), 40 deletions(-) diff --git a/.changeset/lovely-bugs-prove.md b/.changeset/lovely-bugs-prove.md index 5b35402dfb..b1cb762e73 100644 --- a/.changeset/lovely-bugs-prove.md +++ b/.changeset/lovely-bugs-prove.md @@ -2,7 +2,7 @@ '@backstage/repo-tools': minor --- -Renames the `schema openapi *` commands into `package schema openapi *` and `repo schema openapi *`. The aim is to make it more clear what the command is operating on, the entire repo or just a single package. +**BREAKING**: The `schema openapi *` commands are now renamed into `package schema openapi *` and `repo schema openapi *`. The aim is to make it more clear what the command is operating on, the entire repo or just a single package. The following commands now live under the `package` namespace, diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fd6e2edbc3..ddc1712698 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -113,10 +113,10 @@ jobs: run: yarn backstage-repo-tools generate-catalog-info --ci - name: lint openapi yaml files - run: yarn backstage-repo-tools schema openapi lint + run: yarn backstage-repo-tools repo schema openapi lint - name: verify openapi yaml file matches generated ts file - run: yarn backstage-repo-tools schema openapi verify + run: yarn backstage-repo-tools repo schema openapi verify - name: verify doc links run: node scripts/verify-links.js @@ -225,7 +225,7 @@ jobs: # We run the test cases before verifying the specs to prevent any failing tests from causing errors. - name: verify openapi specs against test cases - run: yarn backstage-repo-tools schema openapi test + run: yarn backstage-repo-tools repo schema openapi test - name: ensure clean working directory run: | diff --git a/docs/openapi/generate-client.md b/docs/openapi/generate-client.md index f2c7c64574..640036960e 100644 --- a/docs/openapi/generate-client.md +++ b/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 --output-directory `. This will create a new folder in `/src/generated` to house the generated content. +1. Run `yarn backstage-repo-tools schema openapi generate client --output-package `. This will create a new folder in `/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. diff --git a/docs/openapi/test-case-validation.md b/docs/openapi/test-case-validation.md index 0d93b6d5b5..28d0eb5470 100644 --- a/docs/openapi/test-case-validation.md +++ b/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 diff --git a/packages/repo-tools/cli-report.md b/packages/repo-tools/cli-report.md index be1e7ffceb..3a03e25352 100644 --- a/packages/repo-tools/cli-report.md +++ b/packages/repo-tools/cli-report.md @@ -15,7 +15,8 @@ Commands: api-reports [options] [paths...] type-deps generate-catalog-info [options] - schema [command] + package [command] + repo [command] help [command] ``` @@ -48,10 +49,23 @@ Options: -h, --help ``` -### `backstage-repo-tools schema` +### `backstage-repo-tools package` ``` -Usage: backstage-repo-tools schema [options] [command] [command] +Usage: backstage-repo-tools package [options] [command] [command] + +Options: + -h, --help + +Commands: + schema [command] + help [command] +``` + +### `backstage-repo-tools package schema` + +``` +Usage: backstage-repo-tools package schema [options] [command] [command] Options: -h, --help @@ -61,65 +75,127 @@ Commands: help [command] ``` -### `backstage-repo-tools schema openapi` +### `backstage-repo-tools package schema openapi` ``` -Usage: backstage-repo-tools schema openapi [options] [command] [command] +Usage: backstage-repo-tools package schema openapi [options] [command] [command] + +Options: + -h, --help + +Commands: + init + generate [command] + 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] + +Options: + -h, --help +``` + +### `backstage-repo-tools package schema openapi init` + +``` +Usage: backstage-repo-tools package schema openapi init [options] + +Options: + -h, --help +``` + +### `backstage-repo-tools repo` + +``` +Usage: backstage-repo-tools repo [options] [command] [command] + +Options: + -h, --help + +Commands: + schema [command] + help [command] +``` + +### `backstage-repo-tools repo schema` + +``` +Usage: backstage-repo-tools repo schema [options] [command] [command] + +Options: + -h, --help + +Commands: + openapi [command] + help [command] +``` + +### `backstage-repo-tools repo schema openapi` + +``` +Usage: backstage-repo-tools repo schema openapi [options] [command] [command] Options: -h, --help Commands: verify [paths...] - generate [paths...] lint [options] [paths...] test [options] [paths...] - init help [command] ``` -### `backstage-repo-tools schema openapi generate` +### `backstage-repo-tools repo schema openapi lint` ``` -Usage: backstage-repo-tools schema openapi generate [options] [paths...] - -Options: - -h, --help -``` - -### `backstage-repo-tools schema openapi init` - -``` -Usage: backstage-repo-tools schema openapi init [options] - -Options: - -h, --help -``` - -### `backstage-repo-tools schema openapi lint` - -``` -Usage: backstage-repo-tools schema openapi lint [options] [paths...] +Usage: backstage-repo-tools repo schema openapi lint [options] [paths...] Options: --strict -h, --help ``` -### `backstage-repo-tools schema openapi test` +### `backstage-repo-tools repo schema openapi test` ``` -Usage: backstage-repo-tools schema openapi test [options] [paths...] +Usage: backstage-repo-tools repo schema openapi test [options] [paths...] Options: --update -h, --help ``` -### `backstage-repo-tools schema openapi verify` +### `backstage-repo-tools repo schema openapi verify` ``` -Usage: backstage-repo-tools schema openapi verify [options] [paths...] +Usage: backstage-repo-tools repo schema openapi verify [options] [paths...] Options: -h, --help