Add warning about automatic OpenAPI endpoint generation

organize/navigation.mdx

@@ -96,8 +96,8 @@
 
 Use the `expanded` property to control the default state of a group in the navigation sidebar.
 
 - `expanded: true`: Group is expanded by default.
 - `expanded: false` or omitted: Group is collapsed by default.
 
 This is useful for highlighting important sections or improving discoverability of key content.
 
@@ -254,9 +254,9 @@
 }
 ```
 
 For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path. 
 
 Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal.
 
 ```json
 {
@@ -282,7 +282,7 @@
 
 ## Dropdowns
 
 Dropdowns are contained in an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation.
 
 <img
   className="block dark:hidden pointer-events-none"
@@ -397,8 +397,16 @@
 
 Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.
 
 Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.
 
+<Note>
+  When you add the `openapi` property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for **all endpoints** defined in your OpenAPI specification.
+
+  To control which endpoints appear, explicitly list the desired endpoints in a `pages` array.
+</Note>
+
+For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
+
 ```json
 {
   "navigation": {
@@ -426,8 +434,6 @@
 }
 ```
 
-For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
-
 ## Versions
 
 Partition your navigation into different versions. Versions are selectable from a dropdown menu.
@@ -491,7 +497,7 @@
 
 In the `navigation` object, `languages` is an array where each entry is an object that requires a `language` field and can contain any other navigation fields.
 
 We currently support the following languages for localization:
 
 <CardGroup cols={2}>
   <Card title="Arabic (ar)" icon="/images/navigation/languages/ar.png" horizontal />
@@ -545,7 +551,7 @@
 
 ## Nesting
 
 You can use any combination of anchors, tabs, dropdowns, and products. The components can be nested within each other interchangeably to create your desired navigation structure.
 
 <CodeGroup>
 
@@ -667,7 +673,7 @@
 
 ## Breadcrumbs
 
 Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs are enabled for your site using the `styling` property in your `docs.json`.
 
 <CodeGroup>
 
@@ -691,10 +697,10 @@
 
 ### Enable auto-navigation for groups
 
 When a user expands a navigation group, some themes will automatically navigate to the first page in the group. You can override a theme's default behavior using the `drilldown` option.
 
 - Set to `true` to force automatic navigation to the first page when a navigation group is selected.
 - Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
 - Leave unset to use the theme's default behavior.
 
 <CodeGroup>