diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 978a715ce..dc2034267 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -259,6 +259,10 @@ Add an `openapi` field to any navigation element in your `docs.json` to automati
 
 The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.
 
+<Warning>
+  **Setting the `openapi` property on an anchor, tab, or group automatically generates pages for ALL endpoints in the OpenAPI specification.** This can significantly change your navigation structure and may be a breaking change if you have existing links or bookmarks to specific pages.
+</Warning>
+
 Generated endpoint pages have these default metadata values:
 
 - `title`: The operation's `summary` field, if present. If there is no `summary`, the title is generated from the HTTP method and endpoint.
@@ -277,7 +281,11 @@ There are two approaches for adding endpoint pages into your documentation:
 
 ### Dedicated API sections
 
-Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification are included.
+Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. **All endpoints in the specification are automatically included.**
+
+<Note>
+  When you add an `openapi` field to a navigation element without specifying individual pages, every endpoint defined in that OpenAPI specification will generate a page in your documentation. Review your specification to ensure you want all endpoints to be publicly documented.
+</Note>
 
 ```json {5}
 "navigation": {
@@ -290,7 +298,7 @@ Generate dedicated API sections by adding an `openapi` field to a navigation ele
 }
 ```
 
-To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. Each group can reference its own OpenAPI specification.
+To organize multiple OpenAPI specifications in separate sections of your documentation, assign each specification to a different group in your navigation hierarchy. **Each group with an `openapi` field generates pages for all endpoints in its respective specification.**
 
 ```json {8-11, 15-18}
 "navigation": {
@@ -318,6 +326,10 @@ To organize multiple OpenAPI specifications in separate sections of your documen
 }
 ```
 
+<Warning>
+  In this example, the "Users API" group will generate pages for **every endpoint** in `users-openapi.json`, and the "Admin API" group will generate pages for **every endpoint** in `admin-openapi.json`. If you only want to include specific endpoints, use the [selective endpoints](#selective-endpoints) approach instead.
+</Warning>
+
 <Note>
   The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo.
 </Note>