diff --git a/.changeset/shaggy-books-mate.md b/.changeset/shaggy-books-mate.md new file mode 100644 index 0000000000..db1ca0bb09 --- /dev/null +++ b/.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 diff --git a/plugins/catalog-backend-module-backstage-openapi/README.md b/plugins/catalog-backend-module-backstage-openapi/README.md index 821a1b7878..8df5b5d6c9 100644 --- a/plugins/catalog-backend-module-backstage-openapi/README.md +++ b/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`. diff --git a/plugins/catalog-backend-module-backstage-openapi/config.d.ts b/plugins/catalog-backend-module-backstage-openapi/config.d.ts index ce51640495..376c702999 100644 --- a/plugins/catalog-backend-module-backstage-openapi/config.d.ts +++ b/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; }; }; }; diff --git a/plugins/catalog-backend-module-backstage-openapi/package.json b/plugins/catalog-backend-module-backstage-openapi/package.json index 5d1c109f5c..d9ee9ec6e4 100644 --- a/plugins/catalog-backend-module-backstage-openapi/package.json +++ b/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" }, diff --git a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts index dd94000ad7..971a5fbc47 100644 --- a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts +++ b/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: [ diff --git a/yarn.lock b/yarn.lock index b9f6c22171..4d6d2a36c8 100644 --- a/yarn.lock +++ b/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