From d4979b5178b54806b2e11847c73edc59f99c0514 Mon Sep 17 00:00:00 2001 From: Claire Peng Date: Thu, 9 Apr 2026 10:52:43 +0100 Subject: [PATCH 1/4] add note about API Base URL in descriptor-format docs page Signed-off-by: Claire Peng --- docs/features/software-catalog/descriptor-format.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index f9ab41e37a..2fe890d655 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -937,6 +937,12 @@ API belongs to, e.g. `artist-engagement-portal`. This field is optional. The definition of the API, based on the format defined by `spec.type`. This field is required. +**Note:** Be sure to specify the API base URL of your API within the `spec.definition`. If this is not provided, some widgets (such as OpenAPI) will fallback to the base URL of the Backstage instance. Below are some examples of specifying API base URL for different formats: + +- [OpenAPI 3.x - use the `server` field](https://swagger.io/docs/specification/v3_0/api-host-and-base-path/#:~:text=All%20API%20endpoints%20are%20relative,.com%2Fv1%2Fusers%20.&text=In%20OpenAPI%203.0%2C%20you%20use,base%20URLs%20for%20your%20API.) +- [OpenAPI 2.0 (Swagger) — use `host`, `basePath`, and `schemes`](https://swagger.io/docs/specification/v2_0/api-host-and-base-path/) +- [AsyncAPI - use the `server` field](https://www.asyncapi.com/docs/concepts/asyncapi-document/structure#servers-field) + ## Kind: Group Describes the following entity kind: From f713b2459b5d91c8adde77ffa59324b82e278638 Mon Sep 17 00:00:00 2001 From: Claire Peng Date: Thu, 9 Apr 2026 10:53:47 +0100 Subject: [PATCH 2/4] add note about API Base URL in api-docs plugin Readme Signed-off-by: Claire Peng --- plugins/api-docs/README.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index f71b796ec4..d662526f24 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -340,6 +340,34 @@ import { ApiExplorerPage } from '@backstage/plugin-api-docs'; />; ``` +## Troubleshooting + +### "Try it out" sends requests to the wrong host + +If the **Try it out** feature in the OpenAPI widget sends requests to your Backstage app's URL instead of the actual API host, the OpenAPI spec is missing a `servers` entry. +When no `servers` field is present, Swagger UI falls back to `window.location.origin` — the current page's host — as the base URL for all requests. + +**Fix**: add a `servers` field to your API entity's `spec.definition`: + +```yaml +# catalog-info.yaml +apiVersion: backstage.io/v1alpha1 +kind: API +metadata: + name: my-api +spec: + type: openapi + definition: | + openapi: "3.0.0" + info: + title: My API + version: v1 + servers: + - url: https://api.example.com/v1 # ← specify your api base URL +``` + +If you cannot modify the spec (e.g. it is generated or fetched from an external source), you can work around this by adding a `requestInterceptor` that rewrites the URL — see [Adding `requestInterceptor` to Swagger UI](#adding-requestinterceptor-to-swagger-ui) above. + ## Old Frontend System If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app as outlined in this section. If you are on the new frontend system, you can skip this. From da1784479878a98099d746befe2e8b6eefb40f85 Mon Sep 17 00:00:00 2001 From: Claire Peng Date: Thu, 9 Apr 2026 10:55:39 +0100 Subject: [PATCH 3/4] add changeset for docs updates Signed-off-by: Claire Peng --- .changeset/purple-melons-scream.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/purple-melons-scream.md diff --git a/.changeset/purple-melons-scream.md b/.changeset/purple-melons-scream.md new file mode 100644 index 0000000000..a7add52822 --- /dev/null +++ b/.changeset/purple-melons-scream.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-api-docs': patch +--- + +Update readme to add instructions for custom api base URL From 5185e919cf83464d0d3124c979236c74a944108f Mon Sep 17 00:00:00 2001 From: Claire Peng Date: Thu, 9 Apr 2026 11:42:10 +0100 Subject: [PATCH 4/4] delete trailing whitespace Signed-off-by: Claire Peng --- plugins/api-docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index d662526f24..5cb15e923f 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -358,11 +358,11 @@ metadata: spec: type: openapi definition: | - openapi: "3.0.0" - info: + openapi: "3.0.0" + info: title: My API version: v1 - servers: + servers: - url: https://api.example.com/v1 # ← specify your api base URL ```