From 2715433c80b40fada3bcb6e972bc201706b74f27 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Fri, 13 Feb 2026 13:09:44 +0000 Subject: [PATCH 1/5] docs(catalog): add mention of openapi backend module for support Signed-off-by: Iury Lenon Alves --- docs/features/software-catalog/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 53afb5205e..e2ff558404 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -136,6 +136,14 @@ Your Backstage developer portal can be customized by incorporating [existing open source plugins](https://github.com/backstage/backstage/tree/master/plugins), or by [building your own](../../plugins/index.md). +## OpenAPI and $ref Support + +If you are using OpenAPI specifications that are split into multiple files using `$ref`, standard processing might not resolve them correctly. + +To fix this, you should install the **OpenAPI Catalog Backend Module**. This module helps resolve `$ref` pointers in your YAML documents, bundling them into a single specification for the catalog. + +For installation instructions and usage, see the [catalog-backend-module-openapi README](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-openapi). + ## Links - [[Blog post] Backstage Service Catalog released in alpha](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha) From a9587e4dd10ac03143dcbe0d30a65e2c70279c25 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 23 Feb 2026 21:02:06 +0000 Subject: [PATCH 2/5] docs: move openapi ref support to configuration.md and add install steps Signed-off-by: Iury Lenon Alves --- .../features/software-catalog/configuration.md | 18 ++++++++++++++++++ docs/features/software-catalog/index.md | 8 -------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 3ed027a0a4..e388c327a6 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -366,3 +366,21 @@ Now install your module. ```ts title="packages/backend/src/index.ts" backend.add(eventsModuleCatalogErrors); ``` + +## OpenAPI and $ref Support + +If you are using OpenAPI specifications that are split into multiple files using `$ref`, standard processing might not resolve them correctly. To fix this, you should install the **OpenAPI Catalog Backend Module**. This module helps resolve `$ref` pointers in your YAML documents, bundling them into a single specification for the catalog. + +### Installation + +1. Add the package to your backend: + +```bash title="From your Backstage root directory" +yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-openapi +``` + +2. Register the module in your backend configuration: + +```ts title="packages/backend/src/index.ts" +backend.add(import('@backstage/plugin-catalog-backend-module-openapi')); +``` diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 87e07fd912..a221ed9157 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -136,14 +136,6 @@ Your Backstage developer portal can be customized by incorporating [existing open source plugins](https://github.com/backstage/backstage/tree/master/plugins), or by [building your own](../../plugins/index.md). -## OpenAPI and $ref Support - -If you are using OpenAPI specifications that are split into multiple files using `$ref`, standard processing might not resolve them correctly. - -To fix this, you should install the **OpenAPI Catalog Backend Module**. This module helps resolve `$ref` pointers in your YAML documents, bundling them into a single specification for the catalog. - -For installation instructions and usage, see the [catalog-backend-module-openapi README](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-openapi). - ## Unprocessed Entities Sometimes entities fail to process correctly. The **Unprocessed Entities** feature helps Backstage admins find and diagnose these entities to understand the state of the catalog. From 1a8a464d1d42752454066a87b54bfc063eb70be7 Mon Sep 17 00:00:00 2001 From: Iury Lenon Date: Mon, 23 Feb 2026 21:09:46 +0000 Subject: [PATCH 3/5] Update docs/features/software-catalog/configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Iury Lenon --- docs/features/software-catalog/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index e388c327a6..88a12ceba6 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -379,7 +379,7 @@ If you are using OpenAPI specifications that are split into multiple files using yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-openapi ``` -2. Register the module in your backend configuration: +2. Register the module in your backend: ```ts title="packages/backend/src/index.ts" backend.add(import('@backstage/plugin-catalog-backend-module-openapi')); From 0a39019a4d792399760f63708271258855a6e1a7 Mon Sep 17 00:00:00 2001 From: Iury Lenon Date: Mon, 23 Feb 2026 21:15:09 +0000 Subject: [PATCH 4/5] Update docs/features/software-catalog/configuration.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Iury Lenon --- docs/features/software-catalog/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 88a12ceba6..d9cba22582 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -367,9 +367,9 @@ Now install your module. backend.add(eventsModuleCatalogErrors); ``` -## OpenAPI and $ref Support +## OpenAPI and AsyncAPI Placeholder Support -If you are using OpenAPI specifications that are split into multiple files using `$ref`, standard processing might not resolve them correctly. To fix this, you should install the **OpenAPI Catalog Backend Module**. This module helps resolve `$ref` pointers in your YAML documents, bundling them into a single specification for the catalog. +The **OpenAPI Catalog Backend Module** registers a JSON Schema placeholder resolver for the `openapi` (and `asyncapi`) placeholder keys. This enables you to use `$openapi` and `$asyncapi` references in your catalog entities, while having all underlying `$ref` pointers resolved and bundled as part of the schema processing. ### Installation From 6a8fb13971bae454f1626456442fbce05bcab720 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 23 Feb 2026 21:24:15 +0000 Subject: [PATCH 5/5] docs: add usage example for openapi ref resolution Signed-off-by: Iury Lenon Alves --- .../features/software-catalog/configuration.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index d9cba22582..8c9241eb36 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -384,3 +384,21 @@ yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-openapi ```ts title="packages/backend/src/index.ts" backend.add(import('@backstage/plugin-catalog-backend-module-openapi')); ``` + +### Usage + +To trigger the `$ref` resolution, use the `$openapi` (or `$asyncapi`) placeholder in your catalog entity definition: + +```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 +```