Add OpenAPI Auto-Generation Warnings to Setup Documentation

api-playground/openapi-setup.mdx

@@ -13,12 +13,12 @@
 You can reference multiple OpenAPI specifications to create pages for your API. Either organize sections for each specification in your navigation or reference specific endpoints from different specifications.
 
 <Note>
   Mintlify supports `$ref` for **internal references only** within a single OpenAPI document. External references are not supported.
 </Note>
 
 ### Describe your API
 
 We recommend the following resources to learn about and construct your OpenAPI specification.
 
 - [Swagger's OpenAPI Guide](https://swagger.io/docs/specification/v3_0/basic-structure/) to learn the OpenAPI syntax.
 - [The OpenAPI specification Markdown sources](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/) to reference details of the latest OpenAPI specification.
@@ -92,7 +92,7 @@
 Common authentication types include:
 
 - [API Keys](https://swagger.io/docs/specification/authentication/api-keys/): For header, query, or cookie-based keys.
 - [Bearer](https://swagger.io/docs/specification/authentication/bearer-authentication/): For JWT or OAuth tokens.
 - [Basic](https://swagger.io/docs/specification/authentication/basic-authentication/): For username and password.
 
 If different endpoints within your API require different methods of authentication, you can [override the `security` field](https://swagger.io/docs/specification/authentication/#:~:text=you%20can%20apply%20them%20to%20the%20whole%20API%20or%20individual%20operations%20by%20adding%20the%20security%20section%20on%20the%20root%20level%20or%20operation%20level%2C%20respectively.) for a given operation.
@@ -101,7 +101,7 @@
 
 ## Customize your endpoint pages
 
 Customize your endpoint pages by adding the `x-mint` extension to your OpenAPI specification. The `x-mint` extension provides additional control over how your API documentation is generated and displayed.
 
 ### Metadata
 
@@ -156,7 +156,7 @@
 }
 ```
 
 ### Href
 
 Change the URL of the endpoint page in your docs using `x-mint: href`. When `x-mint: href` is present, the navigation entry links directly to the specified URL instead of generating an API page.
 
@@ -221,7 +221,7 @@
     "/users": {
       "delete": {
         "summary": "Delete user (admin only)",
         // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
         // ...
       }
     }
@@ -257,11 +257,15 @@
 
 Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
 
 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.
 - `description`: The operation's `description` field, if present.
 - `version`: The `version` value from the parent anchor or tab, if present.
 - `deprecated`: The operation's `deprecated` field. If `true`, a deprecated label appears next to the endpoint title in the side navigation and on the endpoint page.
@@ -277,7 +281,11 @@
 
 ### 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 @@
 }
 ```
 
-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,8 +326,12 @@
 }
 ```
 
+<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>
 
 ### Selective endpoints
@@ -358,7 +370,7 @@
 
 #### OpenAPI spec inheritance
 
 OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own.
 
 ```json {3, 7-8, 11, 13-14}
 {
@@ -383,7 +395,7 @@
 
 #### Individual endpoints
 
 Reference specific endpoints without setting a default OpenAPI specification by including the file path. You can reference endpoints from multiple OpenAPI specifications in the same documentation section.
 
 ```json {5-6}
 "navigation": {
@@ -435,7 +447,7 @@
 
 </CodeGroup>
 
 The method and path must exactly match your OpenAPI spec. If you have multiple OpenAPI specifications, include the file path in your reference. External OpenAPI URLs can be referenced in `docs.json`.
 
 #### Autogenerate endpoint pages
 
@@ -446,7 +458,7 @@
 ```
 
 <Tip>
   Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory.
 </Tip>
 
 ### Document data models
@@ -489,7 +501,7 @@
 
 ## Webhooks
 
 Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents.
 
 Add a `webhooks` field to your OpenAPI document alongside the `paths` field.