Merge pull request #22126 from Bonial-International-GmbH/pjungermann/new-backend/catalog-openapi

new backend system: catalog-backend-module-openapi plugin

.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'));
+```

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.

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,

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:^",

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';

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,
+    );
+  });
+});

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,
+          );
+        },
+      });
+    },
+  });

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';

yarn.lock

@@ -5547,6 +5547,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:^"