From 80c0b16e181c1e357227bd1a08b501eebf12ac16 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Fri, 13 Feb 2026 14:06:29 +0000 Subject: [PATCH 1/4] docs(integrations): add mention of backstage-openapi backend module Signed-off-by: Iury Lenon Alves --- docs/integrations/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 00463a810f..89f8e044c3 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -26,3 +26,9 @@ integrations: See documentation for each type of integration for full details on configuration. + +## Backstage OpenAPI Module + +If you want to integrate the OpenAPI specifications from your Backstage instance itself into the catalog, you can use the `catalog-backend-module-backstage-openapi`. This module helps discover and ingest OpenAPI definitions from Backstage plugins. + +For more details, see the [module documentation](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-backstage-openapi). From f75764c7179565b683139c2419bb926460fab396 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 23 Feb 2026 20:37:58 +0000 Subject: [PATCH 2/4] docs: move backstage openapi docs to configuration.md and add install steps Signed-off-by: Iury Lenon Alves --- docs/features/software-catalog/configuration.md | 6 ++++++ docs/integrations/index.md | 6 ------ 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 8c9241eb36..140b186137 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -371,6 +371,12 @@ backend.add(eventsModuleCatalogErrors); 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. +## Backstage OpenAPI Module + +As Backstage increasingly uses OpenAPI to define its core APIs (such as the Catalog and Scaffolder), discovering and interacting with these APIs is essential for integrating external tools. + +You can install the **Backstage OpenAPI Module** to easily expose the OpenAPI specifications for your Backstage instance plugins directly into the catalog. + ### Installation 1. Add the package to your backend: diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 89f8e044c3..00463a810f 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -26,9 +26,3 @@ integrations: See documentation for each type of integration for full details on configuration. - -## Backstage OpenAPI Module - -If you want to integrate the OpenAPI specifications from your Backstage instance itself into the catalog, you can use the `catalog-backend-module-backstage-openapi`. This module helps discover and ingest OpenAPI definitions from Backstage plugins. - -For more details, see the [module documentation](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-backstage-openapi). From d4199a9d282b581019e86e5117f27aeb15450714 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 23 Feb 2026 21:44:36 +0000 Subject: [PATCH 3/4] docs: add required app-config for backstage-openapi module Signed-off-by: Iury Lenon Alves --- docs/features/software-catalog/configuration.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 140b186137..4c50719cb9 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -408,3 +408,14 @@ spec: definition: $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances ``` + +3. Add the configuration to your `app-config.yaml`: + +```yaml title="app-config.yaml" +catalog: + providers: + backstageOpenapi: + plugins: + - catalog + - scaffolder +``` From 346d3302c2781c25e82c20841f12558e20caa252 Mon Sep 17 00:00:00 2001 From: Iury Lenon Alves Date: Mon, 9 Mar 2026 22:52:05 +0000 Subject: [PATCH 4/4] docs: fix markdown hierarchy and apply copilot suggestions Signed-off-by: Iury Lenon Alves --- .../software-catalog/configuration.md | 38 ++++++++++++++++--- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index 4c50719cb9..6ceb00b3b5 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -371,12 +371,6 @@ backend.add(eventsModuleCatalogErrors); 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. -## Backstage OpenAPI Module - -As Backstage increasingly uses OpenAPI to define its core APIs (such as the Catalog and Scaffolder), discovering and interacting with these APIs is essential for integrating external tools. - -You can install the **Backstage OpenAPI Module** to easily expose the OpenAPI specifications for your Backstage instance plugins directly into the catalog. - ### Installation 1. Add the package to your backend: @@ -409,6 +403,28 @@ spec: $openapi: ./spec/openapi.yaml # by using $openapi Backstage will now resolve all $ref instances ``` +## Backstage OpenAPI Module + +As Backstage increasingly uses OpenAPI to define its core APIs (such as the Catalog and Scaffolder), discovering and interacting with these APIs is essential for integrating external tools. + +You can install the **Backstage OpenAPI Module** to easily expose the OpenAPI specifications for your Backstage instance plugins directly into the catalog. + +### Installation + +1. Install the module in your backend: + +```bash +yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-backstage-openapi +``` + +2. Register the module in your backend: + +```ts title="packages/backend/src/index.ts" +backend.add( + import('@backstage/plugin-catalog-backend-module-backstage-openapi'), +); +``` + 3. Add the configuration to your `app-config.yaml`: ```yaml title="app-config.yaml" @@ -418,4 +434,14 @@ catalog: plugins: - catalog - scaffolder + # Optional configuration: + # definitionFormat controls how generated definitions are serialized. + # Supported values: 'json' (default) or 'yaml'. + # definitionFormat: json + # entityOverrides can be used to override parts of the produced entities. + # For example, to add a tag to all generated APIs: + # entityOverrides: + # metadata: + # tags: + # - from-openapi ```