From 7528e1f487552f213f391cede9329c431bf8f740 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 3 Apr 2024 16:32:34 +0900 Subject: [PATCH 01/11] enable custom config of `name` and `title` Signed-off-by: Joe Van Alstyne --- .../src/InternalOpenApiDocumentationProvider.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts index dd94000ad7..ff6e3d522c 100644 --- a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts +++ b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts @@ -229,13 +229,19 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { const pluginsToMerge = this.config.getStringArray( 'catalog.providers.backstageOpenapi.plugins', ); + const name = this.config.getOptionalString( + 'catalog.providers.backstageOpenapi.name', + ); + const title = this.config.getOptionalString( + 'catalog.providers.backstageOpenapi.title', + ); logger.info(`Loading specs from from ${pluginsToMerge}.`); const documentationEntity: ApiEntity = { apiVersion: 'backstage.io/v1beta1', kind: 'API', metadata: { - name: 'INTERNAL_instance_openapi_doc', - title: 'Your Backstage Instance documentation', + name: name ?? 'INTERNAL_instance_openapi_doc', + title: title ?? 'Your Backstage Instance documentation', annotations: { [ANNOTATION_LOCATION]: 'internal-package:@backstage/plugin-catalog-backend-module-backstage-openapi', From 5a079cd70d6bfdb70d40687089498cfdb95214dc Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 3 Apr 2024 16:33:16 +0900 Subject: [PATCH 02/11] add new config options to README.md Signed-off-by: Joe Van Alstyne --- .../catalog-backend-module-backstage-openapi/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/README.md b/plugins/catalog-backend-module-backstage-openapi/README.md index a7f4727669..cd1c5f06c6 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,12 +18,14 @@ backend.add( ); ``` -Add a list of plugins to your config like, +Add a list of plugins (and optionally, a custom name/title) to your config like: ```yaml title="app-config.yaml" catalog: providers: - openapi: + backstageOpenapi: + name: 'internal_backstage_api' # Optional + title: 'Backstage API' # Optional plugins: - catalog - todo From 2e2167a8c589e1014cbd1f17096c7d80224e5d56 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 3 Apr 2024 16:43:44 +0900 Subject: [PATCH 03/11] changesets: minor bump Signed-off-by: Joe Van Alstyne --- .changeset/shaggy-books-mate.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/shaggy-books-mate.md 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 From 89d9e2ee6c741e6a116dfaa4c9a37af25fc39d8d Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 4 Apr 2024 16:23:48 +0900 Subject: [PATCH 04/11] feat: expand config options Signed-off-by: Joe Van Alstyne --- .../InternalOpenApiDocumentationProvider.ts | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts index ff6e3d522c..d55cb05a6d 100644 --- a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts +++ b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts @@ -229,19 +229,22 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { const pluginsToMerge = this.config.getStringArray( 'catalog.providers.backstageOpenapi.plugins', ); - const name = this.config.getOptionalString( - 'catalog.providers.backstageOpenapi.name', - ); - const title = this.config.getOptionalString( - 'catalog.providers.backstageOpenapi.title', - ); - logger.info(`Loading specs from from ${pluginsToMerge}.`); + + const getOverride = (key: string, fallbackValue: string = '') => { + return ( + this.config.getOptionalString( + `catalog.providers.backstageOpenapi.entityOverrides.${key}`, + ) ?? fallbackValue + ); + }; + + logger.info(`Loading specs from ${pluginsToMerge}.`); const documentationEntity: ApiEntity = { apiVersion: 'backstage.io/v1beta1', kind: 'API', metadata: { - name: name ?? 'INTERNAL_instance_openapi_doc', - title: title ?? 'Your Backstage Instance documentation', + name: getOverride('metadata.name', 'backstage_openapi_doc'), + title: getOverride('metadata.title', 'Backstage API Documentation'), annotations: { [ANNOTATION_LOCATION]: 'internal-package:@backstage/plugin-catalog-backend-module-backstage-openapi', @@ -250,9 +253,9 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { }, }, spec: { - type: 'openapi', - lifecycle: 'production', - owner: 'backstage', + type: getOverride('spec.type', 'openapi'), + lifecycle: getOverride('spec.lifecycle', 'production'), + owner: getOverride('spec.owner', 'backstage'), definition: JSON.stringify( await loadSpecs({ baseUrl: this.config.getString('backend.baseUrl'), From 2e22245e4528e5575544d6d73482f57a3c6f327c Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 4 Apr 2024 16:24:37 +0900 Subject: [PATCH 05/11] chore: add config options to Config type Signed-off-by: Joe Van Alstyne --- .../config.d.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/plugins/catalog-backend-module-backstage-openapi/config.d.ts b/plugins/catalog-backend-module-backstage-openapi/config.d.ts index ce51640495..b7f197ca48 100644 --- a/plugins/catalog-backend-module-backstage-openapi/config.d.ts +++ b/plugins/catalog-backend-module-backstage-openapi/config.d.ts @@ -25,6 +25,20 @@ export interface Config { * A list of plugins, whose OpenAPI specs you want to collate in `InternalOpenApiDocumentationProvider`. */ plugins: string[]; + /** + * Options to ovveride the provided entity's default metadata and spec properties + */ + entityOverrides?: { + metadata?: { + name?: string; + title?: string; + }; + spec?: { + type?: string; + lifecycle?: string; + owner?: string; + }; + }; }; }; }; From 431dc50cd44f1f31764fb583513d624047338e24 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 4 Apr 2024 16:25:16 +0900 Subject: [PATCH 06/11] docs: add config options to example Signed-off-by: Joe Van Alstyne --- .../catalog-backend-module-backstage-openapi/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/README.md b/plugins/catalog-backend-module-backstage-openapi/README.md index cd1c5f06c6..8df5b5d6c9 100644 --- a/plugins/catalog-backend-module-backstage-openapi/README.md +++ b/plugins/catalog-backend-module-backstage-openapi/README.md @@ -18,18 +18,22 @@ backend.add( ); ``` -Add a list of plugins (and optionally, a custom name/title) to your config like: +Add a list of plugins and optional entity overrides to your config. For example: ```yaml title="app-config.yaml" catalog: providers: backstageOpenapi: - name: 'internal_backstage_api' # Optional - title: 'Backstage API' # Optional plugins: - 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`. From af8e0e63315da46021d287d28cce62ee0ad2bbb2 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Fri, 5 Apr 2024 15:12:30 +0900 Subject: [PATCH 07/11] Update plugins/catalog-backend-module-backstage-openapi/config.d.ts Co-authored-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Signed-off-by: Joe Van Alstyne --- .../config.d.ts | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/config.d.ts b/plugins/catalog-backend-module-backstage-openapi/config.d.ts index b7f197ca48..e403010951 100644 --- a/plugins/catalog-backend-module-backstage-openapi/config.d.ts +++ b/plugins/catalog-backend-module-backstage-openapi/config.d.ts @@ -28,17 +28,10 @@ export interface Config { /** * Options to ovveride the provided entity's default metadata and spec properties */ - entityOverrides?: { - metadata?: { - name?: string; - title?: string; - }; - spec?: { - type?: string; - lifecycle?: string; - owner?: string; - }; - }; + /** + * Properties to override on the final entity object. + */ + entityOverrides?: object; }; }; }; From 1e851d01911253410977e54e201c310c125f7ae6 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 11 Apr 2024 15:10:09 +0900 Subject: [PATCH 08/11] build: add lodash to @backstage/plugin-catalog-backend-module-backstage-openapi dependencies Signed-off-by: Joe Van Alstyne --- plugins/catalog-backend-module-backstage-openapi/package.json | 1 + yarn.lock | 1 + 2 files changed, 2 insertions(+) diff --git a/plugins/catalog-backend-module-backstage-openapi/package.json b/plugins/catalog-backend-module-backstage-openapi/package.json index c4a26902d2..45bb3e3d7b 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/yarn.lock b/yarn.lock index 1834eb2cf6..34c3fefed3 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5473,6 +5473,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 From ff346bdb6a3400e97b85c8b27bf828b06744d500 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 11 Apr 2024 15:12:07 +0900 Subject: [PATCH 09/11] refactor: use lodash.merge to setup plugin-catalog-backend-module-backstage-openapi config Signed-off-by: Joe Van Alstyne --- .../InternalOpenApiDocumentationProvider.ts | 38 ++++++++++++------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts index d55cb05a6d..bef0626830 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,22 +230,26 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { const pluginsToMerge = this.config.getStringArray( 'catalog.providers.backstageOpenapi.plugins', ); + const configToMerge = this.config.getOptional( + 'catalog.providers.backstageOpenapi.entityOverrides', + ); - const getOverride = (key: string, fallbackValue: string = '') => { - return ( - this.config.getOptionalString( - `catalog.providers.backstageOpenapi.entityOverrides.${key}`, - ) ?? fallbackValue - ); + const baseConfig = { + metadata: { + name: 'internal_backstage_plugin', + title: 'Default Backstage API', + }, + spec: { + owner: 'backstage', + lifecycle: 'production', + }, }; logger.info(`Loading specs from ${pluginsToMerge}.`); - const documentationEntity: ApiEntity = { + const requiredConfig = { apiVersion: 'backstage.io/v1beta1', kind: 'API', metadata: { - name: getOverride('metadata.name', 'backstage_openapi_doc'), - title: getOverride('metadata.title', 'Backstage API Documentation'), annotations: { [ANNOTATION_LOCATION]: 'internal-package:@backstage/plugin-catalog-backend-module-backstage-openapi', @@ -253,9 +258,7 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { }, }, spec: { - type: getOverride('spec.type', 'openapi'), - lifecycle: getOverride('spec.lifecycle', 'production'), - owner: getOverride('spec.owner', 'backstage'), + type: 'openapi', definition: JSON.stringify( await loadSpecs({ baseUrl: this.config.getString('backend.baseUrl'), @@ -267,6 +270,15 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { ), }, }; + + // Overwrite base config 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: [ From 6102b73bb3085ba7655c72c4eb05a47816584c6b Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 11 Apr 2024 15:18:21 +0900 Subject: [PATCH 10/11] refactor: update baseConfig strings Signed-off-by: Joe Van Alstyne --- .../src/InternalOpenApiDocumentationProvider.ts | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts index bef0626830..971a5fbc47 100644 --- a/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts +++ b/plugins/catalog-backend-module-backstage-openapi/src/InternalOpenApiDocumentationProvider.ts @@ -236,12 +236,12 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { const baseConfig = { metadata: { - name: 'internal_backstage_plugin', - title: 'Default Backstage API', + name: 'internal_backstage_openapi_doc', + title: 'Backstage API', }, spec: { - owner: 'backstage', lifecycle: 'production', + owner: 'backstage', }, }; @@ -271,8 +271,9 @@ export class InternalOpenApiDocumentationProvider implements EntityProvider { }, }; - // Overwrite base config with options from config file. + // 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, From ec471d3023743986039d3eed02938b070dd7095a Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Thu, 11 Apr 2024 19:58:47 +0900 Subject: [PATCH 11/11] remove redundant comment in config Signed-off-by: Joe Van Alstyne --- plugins/catalog-backend-module-backstage-openapi/config.d.ts | 3 --- 1 file changed, 3 deletions(-) diff --git a/plugins/catalog-backend-module-backstage-openapi/config.d.ts b/plugins/catalog-backend-module-backstage-openapi/config.d.ts index e403010951..376c702999 100644 --- a/plugins/catalog-backend-module-backstage-openapi/config.d.ts +++ b/plugins/catalog-backend-module-backstage-openapi/config.d.ts @@ -25,9 +25,6 @@ export interface Config { * A list of plugins, whose OpenAPI specs you want to collate in `InternalOpenApiDocumentationProvider`. */ plugins: string[]; - /** - * Options to ovveride the provided entity's default metadata and spec properties - */ /** * Properties to override on the final entity object. */