docs: fix markdown hierarchy and apply copilot suggestions

Signed-off-by: Iury Lenon Alves <iuryalves.uk@gmail.com>
2026-03-09 22:52:05 +00:00
parent d4199a9d28
commit 346d3302c2
1 changed files with 32 additions and 6 deletions
@@ -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
 ```