From 926a4c4d2ce82a789d46e3f0e1ef369dedc76011 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:06:49 +0000 Subject: [PATCH 1/3] Document respect-per-spec-base-path OpenAPI setting Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/api-def/openapi/extensions/base-path.mdx | 2 ++ fern/snippets/openapi-specs.mdx | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/fern/products/api-def/openapi/extensions/base-path.mdx b/fern/products/api-def/openapi/extensions/base-path.mdx index 29f2f26368..cff34be0d7 100644 --- a/fern/products/api-def/openapi/extensions/base-path.mdx +++ b/fern/products/api-def/openapi/extensions/base-path.mdx @@ -17,3 +17,5 @@ servers: paths: /users: ... ``` + +A plain base path applies to the whole API, so in a project with multiple OpenAPI specs only one document's value survives the merge. Enable [`respect-per-spec-base-path`](/learn/api-definitions/openapi/generators-yml-reference#settingsrespect-per-spec-base-path) to give each spec its own base path. diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx index 8ee5fdc568..de1f7fd665 100644 --- a/fern/snippets/openapi-specs.mdx +++ b/fern/snippets/openapi-specs.mdx @@ -211,6 +211,15 @@ api: - OrganizationId ``` + + + Applies each OpenAPI document's plain [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to that document's own endpoints before specs are merged, so every spec keeps its own base path. When `false`, a plain base path is API-wide: in a project with multiple specs, one document's value survives the merge and is prepended to every endpoint, including endpoints from the other specs. + + Parameterized base paths such as `/{tenant}/v1` stay at the API root so their path parameters remain on the client. Two documents declaring differing parameterized base paths report a conflict when this setting is enabled. A base path of `/` has no effect, paths that already carry the prefix aren't prefixed twice, and webhooks are unchanged. + + Projects that compensated for the dropped prefix by putting it in `base_url` should move `base_url` back to the host root when enabling this setting. + + When enabled, groups servers by host into unified environments, enabling APIs with multiple protocols (REST, WebSocket, etc.) to share environment configuration. Environment URL IDs use the server name, with path or protocol suffixes added only when needed to resolve collisions. From 32f20820e5ad6e467e0dbb5003b14b5aa743e2db Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Tue, 8 Sep 2026 16:49:49 +0000 Subject: [PATCH 2/3] Condense respect-per-spec-base-path description Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/snippets/openapi-specs.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx index de1f7fd665..908a12fe72 100644 --- a/fern/snippets/openapi-specs.mdx +++ b/fern/snippets/openapi-specs.mdx @@ -213,11 +213,7 @@ api: - Applies each OpenAPI document's plain [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to that document's own endpoints before specs are merged, so every spec keeps its own base path. When `false`, a plain base path is API-wide: in a project with multiple specs, one document's value survives the merge and is prepended to every endpoint, including endpoints from the other specs. - - Parameterized base paths such as `/{tenant}/v1` stay at the API root so their path parameters remain on the client. Two documents declaring differing parameterized base paths report a conflict when this setting is enabled. A base path of `/` has no effect, paths that already carry the prefix aren't prefixed twice, and webhooks are unchanged. - - Projects that compensated for the dropped prefix by putting it in `base_url` should move `base_url` back to the host root when enabling this setting. + When merging multiple OpenAPI specs, applies each document's [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to its own endpoints only. When `false`, one document's base path is prepended to every endpoint across all specs. Parameterized base paths such as `/{tenant}/v1` stay at the API root, and differing parameterized base paths across documents raise a conflict. If you previously set `base_url` to include the dropped prefix, reset it to the host root. From cb9499d7aa6b19dbf89aa97ce4f7be686a5940b5 Mon Sep 17 00:00:00 2001 From: "devin.logan" Date: Tue, 8 Sep 2026 16:52:03 +0000 Subject: [PATCH 3/3] Move base URL migration note into a callout Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/snippets/openapi-specs.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/fern/snippets/openapi-specs.mdx b/fern/snippets/openapi-specs.mdx index 908a12fe72..a2d243cc0f 100644 --- a/fern/snippets/openapi-specs.mdx +++ b/fern/snippets/openapi-specs.mdx @@ -213,7 +213,11 @@ api: - When merging multiple OpenAPI specs, applies each document's [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to its own endpoints only. When `false`, one document's base path is prepended to every endpoint across all specs. Parameterized base paths such as `/{tenant}/v1` stay at the API root, and differing parameterized base paths across documents raise a conflict. If you previously set `base_url` to include the dropped prefix, reset it to the host root. + When merging multiple OpenAPI specs, applies each document's [`x-fern-base-path`](/learn/api-definitions/openapi/extensions/base-path) to its own endpoints only. When `false`, one document's base path is prepended to every endpoint across all specs. Parameterized base paths such as `/{tenant}/v1` stay at the API root, and differing parameterized base paths across documents raise a conflict. + + + If you worked around the dropped prefix by adding it to your [server URL](/learn/api-definitions/openapi/extensions/server-names) (for example, `https://api.example.com/api/v3`), remove it when enabling this setting. Otherwise the prefix is applied twice. +