diff --git a/.changeset/great-adults-begin.md b/.changeset/great-adults-begin.md new file mode 100644 index 0000000000..697613afc0 --- /dev/null +++ b/.changeset/great-adults-begin.md @@ -0,0 +1,14 @@ +--- +'@backstage/plugin-catalog-backend-module-openapi': patch +--- + +Add support for the new backend system. + +A new backend module for the catalog backend +was added and exported as `default`. + +You can use it with the new backend system like + +```ts title="packages/backend/src/index.ts" +backend.add(import('@backstage/plugin-catalog-backend-module-openapi')); +``` diff --git a/plugins/catalog-backend-module-openapi/README.md b/plugins/catalog-backend-module-openapi/README.md index 6b988e15f5..6a8028895d 100644 --- a/plugins/catalog-backend-module-openapi/README.md +++ b/plugins/catalog-backend-module-openapi/README.md @@ -17,6 +17,33 @@ yarn add --cwd packages/backend @backstage/plugin-catalog-backend-module-openapi ### Adding the plugin to your `packages/backend` +```ts title="packages/backend/src/index.ts" +backend.add(import('@backstage/plugin-catalog-backend-module-openapi')); +``` + +This will add the `jsonSchemaRefPlaceholderResolver` for +the placeholder resolver keys `asyncapi` and `openapi`. + +This allows you to use the `$openapi` placeholder when referencing your OpenAPI specification and `$asyncapi` when referencing your AsyncAPI specifications. This will then resolve all `$ref` instances in your specification. + +You can also use this resolver for other kind of yaml files to resolve $ref pointer. + +```yaml +apiVersion: backstage.io/v1alpha1 +kind: API +metadata: + name: example + description: Example API +spec: + type: openapi + lifecycle: production + owner: team + definition: + $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances +``` + +### Adding the plugin to your `packages/backend` (old backend system) + #### **jsonSchemaRefPlaceholderResolver** The placeholder resolver can be added by importing `jsonSchemaRefPlaceholderResolver` in `src/plugins/catalog.ts` in your `backend` package and adding the following. diff --git a/plugins/catalog-backend-module-openapi/api-report.md b/plugins/catalog-backend-module-openapi/api-report.md index 455816645a..206cfac291 100644 --- a/plugins/catalog-backend-module-openapi/api-report.md +++ b/plugins/catalog-backend-module-openapi/api-report.md @@ -3,6 +3,7 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts +import { BackendFeature } from '@backstage/backend-plugin-api'; import { CatalogProcessor } from '@backstage/plugin-catalog-node'; import { Config } from '@backstage/config'; import { Entity } from '@backstage/catalog-model'; @@ -13,6 +14,10 @@ import { PlaceholderResolverParams } from '@backstage/plugin-catalog-backend'; import { ScmIntegrations } from '@backstage/integration'; import { UrlReader } from '@backstage/backend-common'; +// @public +const catalogModuleJsonSchemaRefPlaceholderResolver: () => BackendFeature; +export default catalogModuleJsonSchemaRefPlaceholderResolver; + // @public (undocumented) export function jsonSchemaRefPlaceholderResolver( params: PlaceholderResolverParams, diff --git a/plugins/catalog-backend-module-openapi/package.json b/plugins/catalog-backend-module-openapi/package.json index 495d5f4f0d..ab6ca057c7 100644 --- a/plugins/catalog-backend-module-openapi/package.json +++ b/plugins/catalog-backend-module-openapi/package.json @@ -34,6 +34,7 @@ "dependencies": { "@apidevtools/json-schema-ref-parser": "^9.0.6", "@backstage/backend-common": "workspace:^", + "@backstage/backend-plugin-api": "workspace:^", "@backstage/catalog-model": "workspace:^", "@backstage/config": "workspace:^", "@backstage/integration": "workspace:^", diff --git a/plugins/catalog-backend-module-openapi/src/index.ts b/plugins/catalog-backend-module-openapi/src/index.ts index 170c925a7f..70ab88c2ff 100644 --- a/plugins/catalog-backend-module-openapi/src/index.ts +++ b/plugins/catalog-backend-module-openapi/src/index.ts @@ -22,3 +22,6 @@ export { jsonSchemaRefPlaceholderResolver } from './jsonSchemaRefPlaceholderReso * @deprecated replaced by jsonSchemaRefPlaceholderResolver */ export const openApiPlaceholderResolver = jsonSchemaRefPlaceholderResolver; + +export * from './module'; +export { default } from './module'; diff --git a/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.test.ts b/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.test.ts new file mode 100644 index 0000000000..cfea25341e --- /dev/null +++ b/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.test.ts @@ -0,0 +1,54 @@ +/* + * 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 { startTestBackend } from '@backstage/backend-test-utils'; +import { PlaceholderResolver } from '@backstage/plugin-catalog-node'; +import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha'; +import { catalogModuleJsonSchemaRefPlaceholderResolver } from './catalogModuleJsonSchemaRefPlaceholderResolver'; +import { jsonSchemaRefPlaceholderResolver } from '../jsonSchemaRefPlaceholderResolver'; + +describe('catalogModuleJsonSchemaRefPlaceholderResolver', () => { + it('should register provider at the catalog extension point', async () => { + const registeredPlaceholderResolvers: { + [key: string]: PlaceholderResolver; + } = {}; + + const extensionPoint = { + addPlaceholderResolver: ( + key: string, + resolver: PlaceholderResolver, + ): void => { + registeredPlaceholderResolvers[key] = resolver; + }, + }; + + await startTestBackend({ + extensionPoints: [[catalogProcessingExtensionPoint, extensionPoint]], + features: [catalogModuleJsonSchemaRefPlaceholderResolver()], + }); + + expect(Object.keys(registeredPlaceholderResolvers)).toEqual([ + 'asyncapi', + 'openapi', + ]); + expect(registeredPlaceholderResolvers.asyncapi).toBe( + jsonSchemaRefPlaceholderResolver, + ); + expect(registeredPlaceholderResolvers.openapi).toBe( + jsonSchemaRefPlaceholderResolver, + ); + }); +}); diff --git a/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.ts b/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.ts new file mode 100644 index 0000000000..053951866a --- /dev/null +++ b/plugins/catalog-backend-module-openapi/src/module/catalogModuleJsonSchemaRefPlaceholderResolver.ts @@ -0,0 +1,48 @@ +/* + * 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 { createBackendModule } from '@backstage/backend-plugin-api'; +import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha'; +import { jsonSchemaRefPlaceholderResolver } from '../jsonSchemaRefPlaceholderResolver'; + +/** + * Registers the jsonSchemaRefPlaceholderResolver + * as placeholder resolver for `$asyncapi` and `$openapi`. + * + * @public + */ +export const catalogModuleJsonSchemaRefPlaceholderResolver = + createBackendModule({ + pluginId: 'catalog', + moduleId: 'json-schema-ref-placeholder-resolver', + register(env) { + env.registerInit({ + deps: { + catalog: catalogProcessingExtensionPoint, + }, + async init({ catalog }) { + catalog.addPlaceholderResolver( + 'asyncapi', + jsonSchemaRefPlaceholderResolver, + ); + catalog.addPlaceholderResolver( + 'openapi', + jsonSchemaRefPlaceholderResolver, + ); + }, + }); + }, + }); diff --git a/plugins/catalog-backend-module-openapi/src/module/index.ts b/plugins/catalog-backend-module-openapi/src/module/index.ts new file mode 100644 index 0000000000..b914472c8d --- /dev/null +++ b/plugins/catalog-backend-module-openapi/src/module/index.ts @@ -0,0 +1,17 @@ +/* + * 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. + */ + +export { catalogModuleJsonSchemaRefPlaceholderResolver as default } from './catalogModuleJsonSchemaRefPlaceholderResolver'; diff --git a/yarn.lock b/yarn.lock index 15212e967e..fefcd817a2 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5544,6 +5544,7 @@ __metadata: dependencies: "@apidevtools/json-schema-ref-parser": ^9.0.6 "@backstage/backend-common": "workspace:^" + "@backstage/backend-plugin-api": "workspace:^" "@backstage/backend-test-utils": "workspace:^" "@backstage/catalog-model": "workspace:^" "@backstage/cli": "workspace:^"