From 6a8fb13971bae454f1626456442fbce05bcab720 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 23 Feb 2026 21:24:15 +0000 Subject: [PATCH] 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 +```