docs: add usage example for openapi ref resolution

Signed-off-by: Iury Lenon Alves <iuryalves.uk@gmail.com>
2026-02-23 21:24:15 +00:00
parent 0a39019a4d
commit 6a8fb13971
1 changed files with 18 additions and 0 deletions
@@ -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
+```