Merge pull request #23952 from jvanalstyne-mdsol/feature/backstage-openapi-config

feat: catalog-backend-module-backstage-openapi: enable configuring entity `name` and `title`

.changeset/shaggy-books-mate.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-backstage-openapi': minor
+---
+
+The name and title of the returned openapi doc entity are now configurable

plugins/catalog-backend-module-backstage-openapi/README.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-This module installs an entity provider that exports a single entity, your Backstage instance documentation, which merges as many backend plugins as you have defined in the config value `catalog.providers.openapi.plugins`.
+This module installs an entity provider that exports a single entity, your Backstage instance documentation, which merges as many backend plugins as you have defined in the config value `catalog.providers.backstageOpenapi.plugins`.
 
 ## Notes
 
@@ -10,7 +10,7 @@ This module installs an entity provider that exports a single entity, your Backs
 
 ## Installation
 
-To your new backend file, add
+To your new backend file, add:
 
 ```ts title="packages/backend/src/index.ts"
 backend.add(
@@ -18,7 +18,7 @@ backend.add(
 );
 ```
 
-Add a list of plugins to your config like,
+Add a list of plugins and optional entity overrides to your config. For example:
 
 ```yaml title="app-config.yaml"
 catalog:
@@ -28,6 +28,12 @@ catalog:
         - catalog
         - todo
         - search
+      entityOverrides: # All optional
+        metadata:
+          name: 'my name'
+          title: 'my title'
+        spec:
+          owner: 'my team'
 ```
 
 We will attempt to load each plugin's OpenAPI spec hosted at `${pluginRoute}/openapi.json`. These are automatically added if you are using `@backstage/backend-openapi-utils`'s `createValidatedOpenApiRouter`.

plugins/catalog-backend-module-backstage-openapi/config.d.ts

@@ -25,6 +25,10 @@ export interface Config {
          * A list of plugins, whose OpenAPI specs you want to collate in `InternalOpenApiDocumentationProvider`.
          */
         plugins: string[];
+        /**
+         * Properties to override on the final entity object.
+         */
+        entityOverrides?: object;
       };
     };
   };

plugins/catalog-backend-module-backstage-openapi/package.json

@@ -39,6 +39,7 @@
     "@backstage/errors": "workspace:^",
     "@backstage/plugin-catalog-node": "workspace:^",
     "cross-fetch": "^4.0.0",
+    "lodash": "^4.17.21",
     "openapi-merge": "^1.3.2",
     "uuid": "^9.0.0"
   },

plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts

@@ -38,7 +38,8 @@ import {
   DiscoveryService,
   LoggerService,
 } from '@backstage/backend-plugin-api';
-import * as uuid from 'uuid';
+import uuid from 'uuid';
+import lodash from 'lodash';
 import { PluginTaskScheduler, TaskRunner } from '@backstage/backend-tasks';
 
 const HTTP_VERBS: (keyof PathItemObject)[] = [
@@ -229,13 +230,26 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider {
     const pluginsToMerge = this.config.getStringArray(
       'catalog.providers.backstageOpenapi.plugins',
     );
-    logger.info(`Loading specs from from ${pluginsToMerge}.`);
-    const documentationEntity: ApiEntity = {
+    const configToMerge = this.config.getOptional(
+      'catalog.providers.backstageOpenapi.entityOverrides',
+    );
+
+    const baseConfig = {
+      metadata: {
+        name: 'internal_backstage_openapi_doc',
+        title: 'Backstage API',
+      },
+      spec: {
+        lifecycle: 'production',
+        owner: 'backstage',
+      },
+    };
+
+    logger.info(`Loading specs from ${pluginsToMerge}.`);
+    const requiredConfig = {
       apiVersion: 'backstage.io/v1beta1',
       kind: 'API',
       metadata: {
-        name: 'INTERNAL_instance_openapi_doc',
-        title: 'Your Backstage Instance documentation',
         annotations: {
           [ANNOTATION_LOCATION]:
             'internal-package:@backstage/plugin-catalog-backend-module-backstage-openapi',
@@ -245,8 +259,6 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider {
       },
       spec: {
         type: 'openapi',
-        lifecycle: 'production',
-        owner: 'backstage',
         definition: JSON.stringify(
           await loadSpecs({
             baseUrl: this.config.getString('backend.baseUrl'),
@@ -258,6 +270,16 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider {
         ),
       },
     };
+
+    // Overwrite baseConfig with options from config file.
+    const mergedConfig = lodash.merge(baseConfig, configToMerge);
+
+    // Overwite mergedConfig with requiredConfig (i.e., spec.type and spec.definition) to avoid bad configuration.
+    const documentationEntity = lodash.merge(
+      mergedConfig,
+      requiredConfig,
+    ) as ApiEntity;
+
     await this.connection?.applyMutation({
       type: 'full',
       entities: [

yarn.lock

@@ -5493,6 +5493,7 @@ __metadata:
     "@backstage/errors": "workspace:^"
     "@backstage/plugin-catalog-node": "workspace:^"
     cross-fetch: ^4.0.0
+    lodash: ^4.17.21
     openapi-merge: ^1.3.2
     openapi3-ts: ^3.1.2
     uuid: ^9.0.0