x-mint

api-playground/mdx/configuration.mdx

@@ -3,7 +3,7 @@
 description: 'Generate docs pages for your API endpoints using `MDX`'
 ---
 
-You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most API documentation projects as it's more maintainable and feature-rich. However, MDX can be useful for documenting small APIs, prototyping, or when you want to feature API endpoints alongside other content.
+You can manually define API endpoints in individual `MDX` files rather than using an OpenAPI specification. This method provides flexibility for custom content, but we recommend generating API documentation from an OpenAPI specification file for most projects because it is more maintainable and feature-rich. However, creating `MDX` pages for an API can be useful to document small APIs, prototyping, or when you want more control over where API endpoints are in the navigation.
 
 To generate pages for API endpoints using `MDX`, configure your API settings in `docs.json`, create individual `MDX` files for each endpoint, and use components like `<ParamFields />` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples.
 
@@ -164,7 +164,7 @@
 ```mdx Page Metadata
 ---
 title: "Your page title"
 authMethod: "none"
 ---
 ```
 </CodeGroup>

api-playground/openapi-setup.mdx

@@ -10,6 +10,8 @@
 
 To document your endpoints with OpenAPI, you need a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification 3.0\+](https://swagger.io/specification/).
 
+You can create API pages from a single or multiple OpenAPI documents.
+
 ### Describing your API
 
 We recommend the following resources to learn about and construct your OpenAPI documents.
@@ -25,7 +27,7 @@
 
 ### Specifying the URL for your API
 
 To enable Mintlify features like the API playground, add a `servers` field to your OpenAPI document with your API's base URL.
 
 ```json
 {
@@ -93,22 +95,117 @@
 
 For more information on defining and applying authentication, see [Authentication](https://swagger.io/docs/specification/authentication/) in the OpenAPI documentation.
 
+## `x-mint` extension
+
+The `x-mint` extension is a custom OpenAPI extension that provides additional control over how your API documentation is generated and displayed.
+
+### Metadata
+
+Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation. You can use any metadata field that would be valid in `MDX` frontmatter except for `openapi`, `version`, or `deprecated`:
+
+```json {7-13}
+{
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Get users",
+        "description": "Retrieve a list of users",
+        "x-mint": {
+          "metadata": {
+            "title": "List all users",
+            "description": "Fetch paginated user data with filtering options",
+            "og:title": "Display a list of users",
+          }
+        },
+        "parameters": [
+          {
+            // Parameter configuration
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Content
+
+Add content before the auto-generated API documentation using `x-mint: content`:
+
+```json {6-13}
+{
+  "paths": {
+    "/users": {
+      "post": {
+        "summary": "Create user",
+        "x-mint": {
+          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
+        },
+        "parameters": [
+          {
+            // Parameter configuration
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+The `content` extension supports all Mintlify MDX components and formatting.
+
+### href
+
+Change the URL of the endpoint page in your docs using `x-mint: href`:
+
+```json {6-8, 14-16}
+{
+  "paths": {
+    "/legacy-endpoint": {
+      "get": {
+        "summary": "Legacy endpoint",
+        "x-mint": {
+          "href": "/deprecated-endpoints/legacy-endpoint"
+        }
+      }
+    },
+    "/documented-elsewhere": {
+      "post": {
+        "summary": "Special endpoint",
+        "x-mint": {
+          "href": "/guides/special-endpoint-guide"
+        }
+      }
+    }
+  }
+}
+```
+
+When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
+
 ## Auto-populate API pages
 
-You can add an `openapi` field to any navigation element in your `docs.json` to auto-populate your docs with a page for each specified endpoint. The `openapi` field can contain the path to an OpenAPI document in your docs repo or the URL of a hosted OpenAPI document.
+Add an `openapi` field to any navigation element in your `docs.json` to automatically generate pages for OpenAPI endpoints. The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.
 
-The metadata for the generated pages will have the following default values:
+Generated endpoint pages have these default metadata values:
 
-- `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
-- `description`: The `description` field from the OpenAPI operation, if present.
-- `version`: The `version` value from the anchor or tab, if present.
-- `deprecated`: The `deprecated` field from the OpenAPI operation, if present. If `true`, a deprecated label will appear next to the endpoint title in the side navigation and on the endpoint page.
+- `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 will appear next to the endpoint title in the side navigation and on the endpoint page.
 
 <Tip>
-  If you have some endpoints in your OpenAPI schema that you want to exclude from your auto-populated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the endpoint.
+  To exclude specific endpoints from your auto-generated API pages, add the [x-hidden](/api-playground/customization/managing-page-visibility#x-hidden) property to the operation in your OpenAPI spec.
 </Tip>
 
-### Example with navigation tabs
+There are two approaches for adding endpoint pages into your documentation:
+
+1. **Dedicated API sections**: Reference OpenAPI specs at the navigation level for dedicated API sections.
+2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages.
+
+### Dedicated API sections
+
+Generate complete API sections by adding an `openapi` field to any navigation element. All endpoints in the specification will be included:
 
 ```json {5}
 "navigation": {
@@ -121,20 +218,27 @@
 }
 ```
 
-### Example with navigation groups
+You can use multiple OpenAPI specifications in different navigation sections:
 
-```json {8-11}
+```json {8-11, 15-18}
 "navigation": {
   "tabs": [
     {
       "tab": "API Reference",
       "groups": [
         {
-          "group": "Endpoints",
+          "group": "Users",
           "openapi": {
             "source": "/path/to/openapi-1.json",
             "directory": "api-reference"
           }
+        },
+        {
+          "group": "Admin",
+          "openapi": {
+            "source": "/path/to/openapi-2.json",
+            "directory": "api-reference"
+          }
         }
       ]
     }
@@ -143,12 +247,14 @@
 ```
 
 <Note>
-  The directory field is optional. If not specified, the files will be placed in the `api-reference` directory of the docs repo.
+  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>
 
 ## Create `MDX` files for API pages
 
-If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you can create `MDX` pages for each operation. See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases).
+For control over individual endpoint pages, create `MDX` pages for each operation. This lets you customize page metadata, add content, omit certain operations, or reorder pages in your navigation at the page level.
+
+See an [example MDX OpenAPI page from MindsDB](https://github.com/mindsdb/mindsdb/blob/main/docs/rest/databases/create-databases.mdx?plain=1) and how it appears in their [live documentation](https://docs.mindsdb.com/rest/databases/create-databases).
 
 ### Manually specify files
 
@@ -158,6 +264,10 @@
 
 If you have multiple OpenAPI files, include the file path in your reference to ensure Mintlify finds the correct OpenAPI document. If you have only one OpenAPI file, Mintlify will detect it automatically.
 
+<Note>
+  This approach works regardless of whether you have set a default OpenAPI spec in your navigation. You can reference any endpoint from any OpenAPI spec by including the file path in the frontmatter.
+</Note>
+
 If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
 
 <CodeGroup>
@@ -190,10 +300,10 @@
 
 ### Autogenerate `MDX` files
 
 Use our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) to autogenerate `MDX` pages for large OpenAPI documents.
 
 <Note>
   Your OpenAPI document must be valid or the files will not autogenerate.
 </Note>
 
 The scraper generates:
@@ -205,12 +315,12 @@
 <Steps>
   <Step title="Generate `MDX` files.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
     ```
   </Step>
   <Step title="Specify an output folder.">
     ```bash
     npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
     ```
 
     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.

api-playground/overview.mdx

@@ -33,9 +33,9 @@
 
   </Step>
   <Step title="Configure `docs.json`.">
-    Update your `docs.json` to reference your OpenAPI specification. You can add an `openapi` property to any navigation element to auto-populate your docs with a page for each endpoint specified in your OpenAPI document.
-    
-    In this example, Mintlify will generate a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
+    Update your `docs.json` to reference your OpenAPI specification. Add an `openapi` property to any navigation element to auto-populate your docs with pages for each endpoint specified in your OpenAPI document.
+
+    This example generates a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
 
     ```json
     {
@@ -73,10 +73,10 @@
 </ResponseField>
 
 <ResponseField name="examples" type="object">
     Configurations for the autogenerated API examples.
     <Expandable title="examples" defaultOpen="True">
     <ResponseField name="languages" type="array of string">
         Example languages for the autogenerated API snippets.
 
         Languages display in the order specified.
     </ResponseField>
@@ -90,7 +90,7 @@
 
 ```json
 {
  "api": {
    "playground": {
      "display": "interactive"
    },
@@ -104,17 +104,21 @@
 
 This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets.
 
-### Custom `MDX` pages
+### Custom endpoint pages
+
+When you need more control over your API documentation, use the `x-mint` extension in your OpenAPI specification or create individual `MDX` pages for your endpoints.
 
-When you need more control over your API documentation, create individual `MDX` pages for your endpoints. This allows you to:
+Both options allow you to:
 
 - Customize page metadata
 - Add additional content like examples
-- Hide specific operations
-- Reorder pages in your navigation
 - Control playground behavior per page
 
-See [MDX Setup](/api-playground/mdx/configuration) for more information on creating individual pages for your API endpoints.
+The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
+
+Individual `MDX` pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.
+
+For more information, see [x-mint extension](/api-playground/openapi-setup#x-mint-extension) and [MDX Setup](/api-playground/mdx/configuration).
 
 ## Further reading
 

navigation.mdx

@@ -243,6 +243,8 @@ Anchors that strictly contain external links can be achieved using the `global`
 }
 ```
 
+---
+
 ## Dropdowns
 
 Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
@@ -290,7 +292,7 @@ While not required, we also recommend that you set an icon for each dropdown ite
 
 ## Versions
 
-Versions can be leveraged to partition your navigation into different versions.
+Partition your navigation into different versions.
 
 <img
   className="block dark:hidden pointer-events-none"
@@ -331,7 +333,7 @@ Versions can be leveraged to partition your navigation into different versions.
 
 ## Languages
 
-Languages can be leveraged to partition your navigation into different languages.
+Partition your navigation into different languages.
 
 <img
   className="block dark:hidden pointer-events-none"