Added example of 2-level nested groups with OpenAPI endpoints

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,11 @@
 
 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.
 
 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 +277,7 @@
 
 ### 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.
 
 ```json {5}
 "navigation": {
@@ -319,9 +319,93 @@
 ```
 
 <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>
 
+#### Nested groups with endpoints
+
+For large APIs with many endpoints, you can create multiple levels of nesting by placing groups within groups. Each nested group can reference specific endpoints from your OpenAPI specification.
+
+```json
+"navigation": {
+  "tabs": [
+    {
+      "tab": "API Reference",
+      "openapi": "/path/to/openapi.json",
+      "groups": [
+        {
+          "group": "Real-Time Communications",
+          "groups": [
+            {
+              "group": "Programmable Voice",
+              "groups": [
+                {
+                  "group": "Call Control",
+                  "pages": [
+                    "GET /calls",
+                    "POST /calls",
+                    "POST /calls/{call_id}/actions/answer",
+                    "POST /calls/{call_id}/actions/hangup"
+                  ]
+                },
+                {
+                  "group": "Conferences",
+                  "pages": [
+                    "GET /conferences",
+                    "POST /conferences",
+                    "POST /conferences/{id}/actions/join"
+                  ]
+                }
+              ]
+            },
+            {
+              "group": "Messaging",
+              "pages": [
+                "POST /messages",
+                "GET /messages/{id}"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "Phone Numbers",
+          "groups": [
+            {
+              "group": "Number Management",
+              "pages": [
+                "GET /phone_numbers",
+                "GET /phone_numbers/{id}",
+                "PATCH /phone_numbers/{id}"
+              ]
+            },
+            {
+              "group": "Number Search",
+              "pages": [
+                "GET /available_phone_numbers"
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+This creates a navigation hierarchy like:
+- **Real-Time Communications**
+  - **Programmable Voice**
+    - **Call Control**
+      - GET /calls
+      - POST /calls
+      - ...
+    - **Conferences**
+      - GET /conferences
+      - ...
+  - **Messaging**
+    - POST /messages
+    - ...
+
 ### Selective endpoints
 
 When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.
@@ -358,7 +442,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 +467,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 +519,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 +530,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 +573,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.