paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 48 Packages Projects Releases Wiki Activity

docs: move openapi ref support to configuration.md and add install steps

Browse Source 
Signed-off-by: Iury Lenon Alves <iuryalves.uk@gmail.com>
This commit is contained in:
Iury Lenon Alves
2026-02-23 21:02:06 +00:00
parent ded468d1c9
commit a9587e4dd1
2 changed files with 18 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-catalog/configuration.md
+18
View File
@@ -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'));
```
docs/features/software-catalog/index.md
-8
View File
@@ -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.