From efd766ea62f8f1aeb883a4e137048a4fec141d9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Fri, 28 Apr 2023 14:38:50 +0200 Subject: [PATCH 1/2] generated openapi files have a new name and notice at the top MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- packages/backend-openapi-utils/README.md | 14 +++++++------- packages/repo-tools/src/commands/index.ts | 2 +- .../repo-tools/src/commands/openapi/constants.ts | 5 ++++- .../repo-tools/src/commands/openapi/generate.ts | 16 +++++++++++++++- .../schema/{openapi.ts => openapi.generated.ts} | 5 +++++ 5 files changed, 32 insertions(+), 10 deletions(-) rename plugins/catalog-backend/src/schema/{openapi.ts => openapi.generated.ts} (99%) diff --git a/packages/backend-openapi-utils/README.md b/packages/backend-openapi-utils/README.md index 51455ccccb..fe22ac2cf2 100644 --- a/packages/backend-openapi-utils/README.md +++ b/packages/backend-openapi-utils/README.md @@ -8,18 +8,18 @@ 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.ts`. In the case of projects that require linting + a license header, you will need to do this manually. +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`, ```ts -import {ApiRouter} from `@backstage/backend-openapi-utils`; -import spec from '../schema/openapi' -... - -export function createRouter(){ +import { ApiRouter } from `@backstage/backend-openapi-utils`; +import spec from '../schema/openapi.generated'; +// ... +export function createRouter() { const router = Router() as ApiRouter; - ... + // ... + return router; } ``` diff --git a/packages/repo-tools/src/commands/index.ts b/packages/repo-tools/src/commands/index.ts index 87d3f7acde..f4d02df3bc 100644 --- a/packages/repo-tools/src/commands/index.ts +++ b/packages/repo-tools/src/commands/index.ts @@ -66,7 +66,7 @@ export function registerCommands(program: Command) { program .command('schema:openapi:verify [paths...]') .description( - 'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.ts` file.', + '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))); diff --git a/packages/repo-tools/src/commands/openapi/constants.ts b/packages/repo-tools/src/commands/openapi/constants.ts index 7c91f423c1..defef4ab53 100644 --- a/packages/repo-tools/src/commands/openapi/constants.ts +++ b/packages/repo-tools/src/commands/openapi/constants.ts @@ -13,6 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + export const YAML_SCHEMA_PATH = 'src/schema/openapi.yaml'; -export const TS_MODULE = 'src/schema/openapi'; + +export const TS_MODULE = 'src/schema/openapi.generated'; + export const TS_SCHEMA_PATH = `${TS_MODULE}.ts`; diff --git a/packages/repo-tools/src/commands/openapi/generate.ts b/packages/repo-tools/src/commands/openapi/generate.ts index fc73013765..e6c9f79f6e 100644 --- a/packages/repo-tools/src/commands/openapi/generate.ts +++ b/packages/repo-tools/src/commands/openapi/generate.ts @@ -18,6 +18,7 @@ import fs from 'fs-extra'; import YAML from 'js-yaml'; import chalk from 'chalk'; import { resolve } from 'path'; +import { paths as cliPaths } from '../../lib/paths'; import { runner } from './runner'; import { TS_SCHEMA_PATH, YAML_SCHEMA_PATH } from './constants'; import { promisify } from 'util'; @@ -41,12 +42,25 @@ async function generate( const tsPath = resolve(directoryPath, TS_SCHEMA_PATH); + // The first set of comment slashes allow for the eslint notice plugin to run + // with onNonMatchingHeader: 'replace', as is the case in the open source + // Backstage repo. Otherwise the auto-generated comment will be removed by the + // lint call below. await fs.writeFile( tsPath, - `export default ${JSON.stringify(yaml, null, 2)} as const`, + `// + +// ****************************************************************** +// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. * +// ****************************************************************** + +export default ${JSON.stringify(yaml, null, 2)} as const;`, ); await exec(`yarn backstage-cli package lint --fix ${tsPath}`); + if (await cliPaths.resolveTargetRoot('node_modules/.bin/prettier')) { + await exec(`yarn prettier --write ${tsPath}`); + } } export async function bulkCommand(paths: string[] = []): Promise { diff --git a/plugins/catalog-backend/src/schema/openapi.ts b/plugins/catalog-backend/src/schema/openapi.generated.ts similarity index 99% rename from plugins/catalog-backend/src/schema/openapi.ts rename to plugins/catalog-backend/src/schema/openapi.generated.ts index 3d775c54cf..e1853f252d 100644 --- a/plugins/catalog-backend/src/schema/openapi.ts +++ b/plugins/catalog-backend/src/schema/openapi.generated.ts @@ -13,6 +13,11 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + +// ****************************************************************** +// * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. * +// ****************************************************************** + export default { openapi: '3.1.0', info: { From 27956d78671ec11d0dc3e066483817d22c1919e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Fri, 28 Apr 2023 14:43:20 +0200 Subject: [PATCH 2/2] changesets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- .changeset/dull-wombats-stare.md | 5 +++++ .changeset/fresh-moons-unite.md | 5 +++++ .changeset/healthy-ladybugs-chew.md | 5 +++++ plugins/catalog-backend/src/service/createRouter.ts | 2 +- 4 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 .changeset/dull-wombats-stare.md create mode 100644 .changeset/fresh-moons-unite.md create mode 100644 .changeset/healthy-ladybugs-chew.md diff --git a/.changeset/dull-wombats-stare.md b/.changeset/dull-wombats-stare.md new file mode 100644 index 0000000000..36ba412c02 --- /dev/null +++ b/.changeset/dull-wombats-stare.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-openapi-utils': patch +--- + +Adjusted README accordingly after the generated output now has a `.generated.ts` extension diff --git a/.changeset/fresh-moons-unite.md b/.changeset/fresh-moons-unite.md new file mode 100644 index 0000000000..3d3af7e698 --- /dev/null +++ b/.changeset/fresh-moons-unite.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Adjusted the OpenAPI schema file name according to the new structure diff --git a/.changeset/healthy-ladybugs-chew.md b/.changeset/healthy-ladybugs-chew.md new file mode 100644 index 0000000000..83f53d5c2c --- /dev/null +++ b/.changeset/healthy-ladybugs-chew.md @@ -0,0 +1,5 @@ +--- +'@backstage/repo-tools': minor +--- + +Generated OpenAPI files now have a `.generated.ts` file name and a warning header at the top, to highlight that they should not be edited by hand. diff --git a/plugins/catalog-backend/src/service/createRouter.ts b/plugins/catalog-backend/src/service/createRouter.ts index 35a6426ae8..5ac1f2eda7 100644 --- a/plugins/catalog-backend/src/service/createRouter.ts +++ b/plugins/catalog-backend/src/service/createRouter.ts @@ -51,7 +51,7 @@ import { validateRequestBody, } from './util'; import type { ApiRouter } from '@backstage/backend-openapi-utils'; -import spec from '../schema/openapi'; +import spec from '../schema/openapi.generated'; import { PluginTaskScheduler } from '@backstage/backend-tasks'; /**