generated openapi files have a new name and notice at the top

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

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 <package-dir> 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 <package-dir> 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<typeof spec>;
-    ...
+    // ...
+    return router;
 }
 ```
 

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)));
 

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`;

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<void> {

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