From a9587e4dd10ac03143dcbe0d30a65e2c70279c25 Mon Sep 17 00:00:00 2001
From: Iury Lenon Alves <iuryalves.uk@gmail.com>
Date: Mon, 23 Feb 2026 21:02:06 +0000
Subject: [PATCH] docs: move openapi ref support to configuration.md and add
 install steps

Signed-off-by: Iury Lenon Alves <iuryalves.uk@gmail.com>
---
 .../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.