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] 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
   ```
 </ParamField>
+
+<ParamField path="settings.respect-per-spec-base-path" type="boolean" default="false" toc={true}>
+  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.
+</ParamField>
+
 <ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
   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.