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] 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: {