feat(repo-tools): Update OpenAPI command naming.

fixes: https://github.com/backstage/backstage/issues/21790 Signed-off-by: Aramis <sennyeyaramis@gmail.com>
2024-01-18 18:00:01 -05:00
parent 086294bda1
commit ff3a604dae
15 changed files with 195 additions and 125 deletions
@@ -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 <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. You should add this command to your `package.json` for future use.

 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 --output-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.

@@ -18,12 +18,71 @@ import { assertError } from '@backstage/errors';
 import { Command } from 'commander';
 import { exitWithError } from '../lib/errors';

-function registerSchemaCommand(program: Command) {
+function registerPackageCommand(program: Command) {
  const command = program
+    .command('package [command]')
+    .description('Various tools for working with specific packages.');
+
+  const schemaCommand = command
+    .command('schema [command]')
+    .description(
+      "Various tools for working with specific packages' API schema",
+    );
+
+  const openApiCommand = schemaCommand
+    .command('openapi [command]')
+    .description('Tooling for OpenAPI schema');
+
+  openApiCommand
+    .command('init')
+    .description('Initialize any required files to use the OpenAPI tooling.')
+    .action(
+      lazy(() => import('./package/schema/openapi/init').then(m => m.default)),
+    );
+
+  const generateCommand = openApiCommand
+    .command('generate [command]')
+    .description(
+      'Commands for generating various things from an OpenAPI spec.',
+    );
+
+  generateCommand
+    .command('server')
+    .description(
+      'Generates an express server stub using the OpenAPI schema for typings.',
+    )
+    .action(
+      lazy(() =>
+        import('./package/schema/openapi/generate/server').then(m => m.command),
+      ),
+    );
+
+  generateCommand
+    .command('client')
+    .description(
+      'Generates a client that can interact with your backend plugin using types from your OpenAPI schema.',
+    )
+    .requiredOption(
+      '--output-package <pathToPackage>',
+      'Top-level path to where the client should be generated, ie packages/catalog-client.',
+    )
+    .action(
+      lazy(() =>
+        import('./package/schema/openapi/generate/client').then(m => m.command),
+      ),
+    );
+}
+
+function registerRepoCommand(program: Command) {
+  const command = program
+    .command('repo [command]')
+    .description('Tools for working across your entire repository.');
+
+  const schemaCommand = command
    .command('schema [command]')
    .description('Various tools for working with API schema');

-  const openApiCommand = command
+  const openApiCommand = schemaCommand
    .command('openapi [command]')
    .description('Tooling for OpenApi schema');

@@ -33,16 +92,9 @@ function registerSchemaCommand(program: Command) {
      'Verify that all OpenAPI schemas are valid and have a matching `schemas/openapi.generated.ts` file.',
    )
    .action(
-      lazy(() => import('./openapi/schema/verify').then(m => m.bulkCommand)),
-    );
-
-  openApiCommand
-    .command('generate [paths...]')
-    .description(
-      'Generates a Typescript file from an OpenAPI yaml spec. For use with the `@backstage/backend-openapi-utils` ApiRouter type.',
-    )
-    .action(
-      lazy(() => import('./openapi/schema/generate').then(m => m.bulkCommand)),
+      lazy(() =>
+        import('./repo/schema/openapi/verify').then(m => m.bulkCommand),
+      ),
    );

  openApiCommand
@@ -52,27 +104,16 @@ function registerSchemaCommand(program: Command) {
      '--strict',
      'Fail on any linting severity messages, not just errors.',
    )
-    .action(lazy(() => import('./openapi/lint').then(m => m.bulkCommand)));
+    .action(
+      lazy(() => import('./repo/schema/openapi/lint').then(m => m.bulkCommand)),
+    );

  openApiCommand
    .command('test [paths...]')
    .description('Test OpenAPI schemas against written tests')
    .option('--update', 'Update the spec on failure.')
-    .action(lazy(() => import('./openapi/test').then(m => m.bulkCommand)));
-
-  openApiCommand
-    .command('init <paths...>')
-    .description('Creates any config needed for the test command.')
-    .action(lazy(() => import('./openapi/test/init').then(m => m.default)));
-
-  openApiCommand
-    .command('generate-client')
-    .requiredOption('--input-spec <file>')
-    .requiredOption('--output-directory <directory>')
    .action(
-      lazy(() =>
-        import('./openapi/client/generate').then(m => m.singleCommand),
-      ),
+      lazy(() => import('./repo/schema/openapi/test').then(m => m.bulkCommand)),
    );
 }

@@ -139,8 +180,8 @@ export function registerCommands(program: Command) {
        ),
      ),
    );
-
-  registerSchemaCommand(program);
+  registerPackageCommand(program);
+  registerRepoCommand(program);
 }

 // Wraps an action function so that it always exits and handles errors
@@ -16,16 +16,23 @@

 import chalk from 'chalk';
 import { resolve } from 'path';
-import { OPENAPI_IGNORE_FILES, OUTPUT_PATH } from '../constants';
-import { paths as cliPaths } from '../../../lib/paths';
+import {
+  OPENAPI_IGNORE_FILES,
+  OUTPUT_PATH,
+} from '../../../../../lib/openapi/constants';
+import { paths as cliPaths } from '../../../../../lib/paths';
 import { mkdirpSync } from 'fs-extra';
 import fs from 'fs-extra';
-import { exec } from '../../../lib/exec';
+import { exec } from '../../../../../lib/exec';
 import { resolvePackagePath } from '@backstage/backend-common';
+import { getPathToCurrentOpenApiSpec } from '../../../../../lib/openapi/helpers';

-async function generate(spec: string, outputDirectory: string) {
-  const resolvedOpenapiPath = resolve(spec);
-  const resolvedOutputDirectory = resolve(outputDirectory, OUTPUT_PATH);
+async function generate(outputDirectory: string) {
+  const resolvedOpenapiPath = await getPathToCurrentOpenApiSpec();
+  const resolvedOutputDirectory = cliPaths.resolveTargetRoot(
+    outputDirectory,
+    OUTPUT_PATH,
+  );
  mkdirpSync(resolvedOutputDirectory);

  await fs.mkdirp(resolvedOutputDirectory);
@@ -80,19 +87,19 @@ async function generate(spec: string, outputDirectory: string) {
  });
 }

-export async function singleCommand({
-  inputSpec,
-  outputDirectory,
+export async function command({
+  outputPackage,
 }: {
-  inputSpec: string;
-  outputDirectory: string;
+  outputPackage: string;
 }): Promise<void> {
  try {
-    await generate(inputSpec, outputDirectory);
-    console.log(chalk.green(`Generated client for ${inputSpec}`));
+    await generate(outputPackage);
+    console.log(
+      chalk.green(`Generated client in ${outputPackage}/${OUTPUT_PATH}`),
+    );
  } catch (err) {
    console.log();
-    console.log(chalk.red(`Client generation failed in ${outputDirectory}:`));
+    console.log(chalk.red(`Client generation failed:`));
    console.log(err);

    process.exit(1);
@@ -17,30 +17,19 @@
 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 { paths as cliPaths } from '../../../../../lib/paths';
+import { TS_SCHEMA_PATH } from '../../../../../lib/openapi/constants';
 import { promisify } from 'util';
 import { exec as execCb } from 'child_process';
+import { getPathToCurrentOpenApiSpec } from '../../../../../lib/openapi/helpers';

 const exec = promisify(execCb);

-async function generate(
-  directoryPath: string,
-  config?: { skipMissingYamlFile: boolean },
-) {
-  const { skipMissingYamlFile } = config ?? {};
-  const openapiPath = resolve(directoryPath, YAML_SCHEMA_PATH);
-  if (!(await fs.pathExists(openapiPath))) {
-    if (skipMissingYamlFile) {
-      return;
-    }
-    throw new Error(`Could not find ${YAML_SCHEMA_PATH} in root of directory.`);
-  }
+async function generate() {
+  const openapiPath = await getPathToCurrentOpenApiSpec();
  const yaml = YAML.load(await fs.readFile(openapiPath, 'utf8'));

-  const tsPath = resolve(directoryPath, TS_SCHEMA_PATH);
+  const tsPath = cliPaths.resolveTarget(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
@@ -63,33 +52,19 @@ export const createOpenApiRouter = async (

  await exec(`yarn backstage-cli package lint --fix ${tsPath}`);
  if (await cliPaths.resolveTargetRoot('node_modules/.bin/prettier')) {
-    await exec(`yarn prettier --write ${tsPath}`);
+    await exec(`yarn prettier --write ${tsPath}`, {
+      cwd: cliPaths.targetRoot,
+    });
  }
 }

-export async function bulkCommand(paths: string[] = []): Promise<void> {
-  const resultsList = await runner(paths, (dir: string) =>
-    generate(dir, { skipMissingYamlFile: true }),
-  );
-
-  let failed = false;
-  for (const { relativeDir, resultText } of resultsList) {
-    if (resultText) {
-      console.log();
-      console.log(
-        chalk.red(
-          `OpenAPI yaml to Typescript generation failed in ${relativeDir}:`,
-        ),
-      );
-      console.log(resultText.trimStart());
-
-      failed = true;
-    }
-  }
-
-  if (failed) {
-    process.exit(1);
-  } else {
+export async function command(): Promise<void> {
+  try {
+    await generate();
    console.log(chalk.green('Generated all files.'));
+  } catch (err) {
+    console.log(chalk.red(`OpenAPI server stub generation failed.`));
+    console.log(err.message);
+    process.exit(1);
  }
 }
@@ -15,12 +15,12 @@
 */
 import fs from 'fs-extra';
 import { join } from 'path';
-import { YAML_SCHEMA_PATH } from './../constants';
+import { YAML_SCHEMA_PATH } from '../../../../lib/openapi/constants';

-import { paths as cliPaths } from '../../../lib/paths';
-import { runner } from '../runner';
+import { paths as cliPaths } from '../../../../lib/paths';
+import { runner } from '../../../../lib/runner';
 import chalk from 'chalk';
-import { exec } from '../../../lib/exec';
+import { exec } from '../../../../lib/exec';

 const ROUTER_TEST_PATHS = [
  'src/service/router.test.ts',
@@ -31,7 +31,7 @@ async function init(directoryPath: string) {
  const openapiPath = join(directoryPath, YAML_SCHEMA_PATH);
  if (!(await fs.pathExists(openapiPath))) {
    throw new Error(
-      `You do not have an OpenAPI YAML file at ${openapiPath}. Please create one and retry this command. If you already have existing test cases for your router, see 'backstage-repo-tools schema openapi test --update'`,
+      `You do not have an OpenAPI YAML file at ${openapiPath}. Please create one and retry this command. If you already have existing test cases for your router, see 'backstage-repo-tools package schema openapi test --update'`,
    );
  }
  const opticConfigFilePath = join(directoryPath, 'optic.yml');
@@ -24,24 +24,19 @@ import { Yaml } from '@stoplight/spectral-parsers';
 import ruleset from '@apisyouwonthate/style-guide';
 import fs from 'fs-extra';
 import chalk from 'chalk';
-import { resolve } from 'path';
-import { runner } from './runner';
-import { YAML_SCHEMA_PATH } from './constants';
+import { runner } from '../../../../lib/runner';
 import { oas } from '@stoplight/spectral-rulesets';
 import { DiagnosticSeverity } from '@stoplight/types';
 import { pretty } from '@stoplight/spectral-formatters';
+import { getPathToOpenApiSpec } from '../../../../lib/openapi/helpers';

-async function lint(
-  directoryPath: string,
-  config?: { skipMissingYamlFile: boolean; strict: boolean },
-) {
-  const { skipMissingYamlFile, strict } = config ?? {};
-  const openapiPath = resolve(directoryPath, YAML_SCHEMA_PATH);
-  if (!(await fs.pathExists(openapiPath))) {
-    if (skipMissingYamlFile) {
-      return;
-    }
-    throw new Error(`Could not find a file at ${openapiPath}.`);
+async function lint(directoryPath: string, config?: { strict: boolean }) {
+  const { strict } = config ?? {};
+  let openapiPath = '';
+  try {
+    openapiPath = await getPathToOpenApiSpec(directoryPath);
+  } catch {
+    return;
  }
  const openapiFileContent = await fs.readFile(openapiPath, 'utf8');

@@ -90,7 +85,7 @@ export async function bulkCommand(
  options: { strict?: boolean },
 ): Promise<void> {
  const resultsList = await runner(paths, (dir: string) =>
-    lint(dir, { skipMissingYamlFile: true, strict: !!options.strict }),
+    lint(dir, { strict: !!options.strict }),
  );

  let failed = false;
@@ -17,18 +17,22 @@
 import fs from 'fs-extra';
 import { join } from 'path';
 import chalk from 'chalk';
-import { runner } from '../runner';
-import { YAML_SCHEMA_PATH } from '../constants';
-import { paths as cliPaths } from '../../../lib/paths';
-import { exec } from '../../../lib/exec';
+import { runner } from '../../../../lib/runner';
+import { YAML_SCHEMA_PATH } from '../../../../lib/openapi/constants';
+import { paths as cliPaths } from '../../../../lib/paths';
+import { exec } from '../../../../lib/exec';
+import { getPathToOpenApiSpec } from '../../../../lib/openapi/helpers';

 async function test(
  directoryPath: string,
  { port }: { port: number },
  options?: { update?: boolean },
 ) {
-  const openapiPath = join(directoryPath, YAML_SCHEMA_PATH);
-  if (!(await fs.pathExists(openapiPath))) {
+  let openapiPath = join(directoryPath, YAML_SCHEMA_PATH);
+  try {
+    openapiPath = await getPathToOpenApiSpec(directoryPath);
+  } catch {
+    // OpenAPI schema doesn't exist.
    return;
  }
  const opticConfigFilePath = join(directoryPath, 'optic.yml');
@@ -21,13 +21,21 @@ import { join } from 'path';
 import chalk from 'chalk';
 import { relative as relativePath, resolve as resolvePath } from 'path';
 import Parser from '@apidevtools/swagger-parser';
-import { runner } from '../runner';
-import { paths as cliPaths } from '../../../lib/paths';
-import { TS_MODULE, TS_SCHEMA_PATH, YAML_SCHEMA_PATH } from '../constants';
+import { runner } from '../../../../lib/runner';
+import { paths as cliPaths } from '../../../../lib/paths';
+import {
+  TS_MODULE,
+  TS_SCHEMA_PATH,
+  YAML_SCHEMA_PATH,
+} from '../../../../lib/openapi/constants';
+import { getPathToOpenApiSpec } from '../../../../lib/openapi/helpers';

 async function verify(directoryPath: string) {
-  const openapiPath = join(directoryPath, YAML_SCHEMA_PATH);
-  if (!(await fs.pathExists(openapiPath))) {
+  let openapiPath = '';
+  try {
+    openapiPath = await getPathToOpenApiSpec(directoryPath);
+  } catch {
+    // Unable to find spec at path.
    return;
  }

@@ -47,7 +55,7 @@ async function verify(directoryPath: string) {
  if (!isEqual(schema.spec, yaml)) {
    const path = relativePath(cliPaths.targetRoot, directoryPath);
    throw new Error(
-      `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn backstage-repo-tools schema openapi generate ${path}\` to regenerate \`${TS_SCHEMA_PATH}\`.`,
+      `\`${YAML_SCHEMA_PATH}\` and \`${TS_SCHEMA_PATH}\` do not match. Please run \`yarn backstage-repo-tools package schema openapi generate\` from '${path}' to regenerate \`${TS_SCHEMA_PATH}\`.`,
    );
  }
 }
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { pathExists } from 'fs-extra';
+import { paths } from '../paths';
+import { YAML_SCHEMA_PATH } from './constants';
+import { resolve } from 'path';
+
+export const getPathToOpenApiSpec = async (directory: string) => {
+  const openapiPath = resolve(directory, YAML_SCHEMA_PATH);
+  if (!(await pathExists(openapiPath))) {
+    throw new Error(`Could not find ${YAML_SCHEMA_PATH}.`);
+  }
+  return openapiPath;
+};
+
+export const getPathToCurrentOpenApiSpec = async () => {
+  return await getPathToOpenApiSpec(paths.targetDir);
+};
@@ -14,10 +14,10 @@
 * limitations under the License.
 */

-import { resolvePackagePaths } from '../../lib/paths';
+import { resolvePackagePaths } from './paths';
 import pLimit from 'p-limit';
 import { relative as relativePath } from 'path';
-import { paths as cliPaths } from '../../lib/paths';
+import { paths as cliPaths } from './paths';
 import portFinder from 'portfinder';

 export async function runner(
@@ -42,7 +42,9 @@
    "test": "backstage-cli package test",
    "prepack": "backstage-cli package prepack",
    "postpack": "backstage-cli package postpack",
-    "clean": "backstage-cli package clean"
+    "clean": "backstage-cli package clean",
+    "generate-server": "backstage-repo-tools package schema openapi generate server",
+    "generate-client": "backstage-repo-tools package schema openapi generate client --output-package packages/catalog-client"
  },
  "dependencies": {
    "@backstage/backend-common": "workspace:^",
@@ -61,6 +63,7 @@
    "@backstage/plugin-permission-common": "workspace:^",
    "@backstage/plugin-permission-node": "workspace:^",
    "@backstage/plugin-search-backend-module-catalog": "workspace:^",
+    "@backstage/repo-tools": "workspace:^",
    "@backstage/types": "workspace:^",
    "@opentelemetry/api": "^1.3.0",
    "@types/express": "^4.17.6",
@@ -39,7 +39,8 @@
    "test": "backstage-cli package test",
    "prepack": "backstage-cli package prepack",
    "postpack": "backstage-cli package postpack",
-    "clean": "backstage-cli package clean"
+    "clean": "backstage-cli package clean",
+    "generate-server": "backstage-repo-tools package schema openapi generate server"
  },
  "dependencies": {
    "@backstage/backend-common": "workspace:^",
@@ -26,7 +26,8 @@
    "prepack": "backstage-cli package prepack",
    "postpack": "backstage-cli package postpack",
    "clean": "backstage-cli package clean",
-    "start": "backstage-cli package start"
+    "start": "backstage-cli package start",
+    "generate-server": "backstage-repo-tools package schema openapi generate server"
  },
  "dependencies": {
    "@backstage/backend-common": "workspace:^",
@@ -38,6 +39,7 @@
    "@backstage/errors": "workspace:^",
    "@backstage/integration": "workspace:^",
    "@backstage/plugin-catalog-node": "workspace:^",
+    "@backstage/repo-tools": "workspace:^",
    "@types/express": "^4.17.6",
    "express": "^4.17.1",
    "leasot": "^12.0.0",
@@ -5560,6 +5560,7 @@ __metadata:
    "@backstage/plugin-permission-common": "workspace:^"
    "@backstage/plugin-permission-node": "workspace:^"
    "@backstage/plugin-search-backend-module-catalog": "workspace:^"
+    "@backstage/repo-tools": "workspace:^"
    "@backstage/types": "workspace:^"
    "@opentelemetry/api": ^1.3.0
    "@types/core-js": ^2.5.4
@@ -9350,6 +9351,7 @@ __metadata:
    "@backstage/errors": "workspace:^"
    "@backstage/integration": "workspace:^"
    "@backstage/plugin-catalog-node": "workspace:^"
+    "@backstage/repo-tools": "workspace:^"
    "@types/express": ^4.17.6
    "@types/supertest": ^2.0.8
    express: ^4.17.1
@@ -9550,7 +9552,7 @@ __metadata:
  languageName: unknown
  linkType: soft

-"@backstage/repo-tools@workspace:*, @backstage/repo-tools@workspace:packages/repo-tools":
+"@backstage/repo-tools@workspace:*, @backstage/repo-tools@workspace:^, @backstage/repo-tools@workspace:packages/repo-tools":
  version: 0.0.0-use.local
  resolution: "@backstage/repo-tools@workspace:packages/repo-tools"
  dependencies: