From 2924b1f0a9ecfbb5add6a2359188e4b81b40a3a3 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Thu, 17 Jul 2025 15:37:15 -0700
Subject: [PATCH 01/20] add troubleshooting info
---
api-playground/troubleshooting.mdx | 53 ++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index 8af5a94a..68450571 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -71,4 +71,57 @@ If your API pages aren't displaying correctly, check these common configuration
Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described in the [settings documentation](/settings#param-proxy). When using this configuration, you will need to configure CORS on your server since requests will come directly from users' browsers rather than through your proxy.
+
+ If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
+
+ 1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set at the navigation level:
+ ```json
+ {
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "pages": ["GET /users", "POST /users"]
+ }
+ }
+ ```
+
+ 2. **Incorrect operation format**: Navigation entries must exactly match the HTTP method and path in your OpenAPI spec:
+ - Correct: `"GET /users/{id}"`
+ - Incorrect: `"get /users/{id}"` (wrong case)
+ - Incorrect: `"GET /users/{id}/"` (extra trailing slash)
+
+ 3. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
+
+ 4. **Validation issues**: Use `mint openapi-check ` to verify your OpenAPI document is valid.
+
+
+
+ 1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
+
+ 2. **Manual vs automatic inclusion**: If you have a `pages` array in your navigation group, only the operations explicitly listed will appear. Remove the `pages` array to include all operations automatically.
+
+ 3. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
+
+
+ When combining OpenAPI operations with regular documentation pages in navigation:
+
+ 1. **Default OpenAPI spec required**: You must set a default OpenAPI spec at the navigation level for automatic operation detection:
+ ```json
+ {
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "pages": [
+ "introduction",
+ "GET /users",
+ "guides/authentication"
+ ]
+ }
+ }
+ ```
+
+ 2. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation.
+
+ 3. **Path resolution**: Navigation entries that don't match OpenAPI operations will be treated as file paths. Ensure your `MDX` files exist at the expected locations.
+
+ 4. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
+
From 0ae7f5f747b6cbe40d60307d5f96a657e5044b43 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 08:42:40 -0700
Subject: [PATCH 02/20] update conceptual info in MDX setup
---
api-playground/mdx/configuration.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx
index 4d989cdc..c7eb6a46 100644
--- a/api-playground/mdx/configuration.mdx
+++ b/api-playground/mdx/configuration.mdx
@@ -3,7 +3,7 @@ title: 'MDX setup'
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 or for prototyping.
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 `` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples.
From 3f1ad1d108f04639219524daaabbdf45b2351432 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 09:28:17 -0700
Subject: [PATCH 03/20] add OpenAPI section to navigation page
---
navigation.mdx | 47 ++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 42 insertions(+), 5 deletions(-)
diff --git a/navigation.mdx b/navigation.mdx
index e6c6f60c..6fe7d09f 100644
--- a/navigation.mdx
+++ b/navigation.mdx
@@ -189,8 +189,6 @@ While not required, we highly recommend that you set an `icon` field as well.
}
```
----
-
Anchors that strictly contain external links can be achieved using the `global` keyword:
```json
@@ -213,6 +211,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.
@@ -260,9 +260,46 @@ While not required, we also recommend that you set an icon for each dropdown ite
---
+## OpenAPI
+
+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.
+
+```json
+{
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "tabs": [
+ {
+ "tab": "API v1 reference",
+ "pages": [
+ "overview",
+ "authentication",
+ "GET /users",
+ "POST /users"
+ ]
+ },
+ {
+ "tab": "API v2 reference",
+ "openapi": "/specs/v2.json",
+ "pages": [
+ "GET /users",
+ "POST /users"
+ ]
+ }
+ ]
+ }
+}
+```
+
+For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
+
+---
+
## Versions
-Versions can be leveraged to partition your navigation into different versions.
+Partition your navigation into different versions.
![]()
\ No newline at end of file
+
From b5e42039ef94d805c7716d98d1d6e8c41f7b40f2 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 11:25:17 -0700
Subject: [PATCH 04/20] update overview steps
---
api-playground/overview.mdx | 23 +++++++++++++++++++++--
1 file changed, 21 insertions(+), 2 deletions(-)
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index 1fc8aca5..0c44ba47 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -33,8 +33,8 @@ We recommend generating your API playground from an OpenAPI specification. See [
- 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.
-
+ 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.
+
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.
```json
@@ -48,6 +48,25 @@ We recommend generating your API playground from an OpenAPI specification. See [
}
```
+ To generate pages for only specific endpoints, list the endpoints in the `pages` property of the navigation element.
+
+ In this example, only pages for the `GET /users` and `POST /users` endpoints will be generated regardless of what other endpoints are specified in `openapi.json`.
+
+ ```json
+ {
+ "navigation": [
+ {
+ "group": "API reference",
+ "openapi": "openapi.json",
+ "pages": [
+ "GET /users",
+ "POST /users"
+ ]
+ }
+ ]
+ }
+ ```
+
From 567c6e676bbebd53b3899e7e890be969340c90cc Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 11:31:18 -0700
Subject: [PATCH 05/20] Update info about customizing endpoint pages
---
api-playground/overview.mdx | 14 +++++++++-----
1 file changed, 9 insertions(+), 5 deletions(-)
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index 0c44ba47..d786a46a 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -123,17 +123,21 @@ You can customize your API playground by defining the following properties in yo
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, create individual `MDX` pages for your endpoints. This allows you to:
+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.
+
+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 reccomended 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](/api-playground/openapi-setup#x-mint) and [MDX Setup](/api-playground/mdx/configuration).
## Further reading
From 52361307d2a1681982d6e441fb8e376aaa062075 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 13:39:18 -0700
Subject: [PATCH 06/20] update setup information
---
api-playground/openapi-setup.mdx | 200 ++++++++++++++++++++++++++++++-
1 file changed, 197 insertions(+), 3 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 9115a21b..ddfc1e42 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -93,10 +93,116 @@ If different endpoints within your API require different methods of authenticati
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:
+
+```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
+ }
+ ]
+ }
+ }
+ }
+}
+```
+
+TODO: what metadata fields are supported?
+
+The `metadata` extension supports:
+- `title`: Override the page title (defaults to operation summary)
+- `description`: Override the page description (defaults to operation description)
+- `og:title`: Override the Open Graph title (defaults to operation summary)
+- `og:description`: Override the Open Graph description (defaults to operation description)
+
+### 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
+ This endpoint requires admin privileges and has rate limiting.
+
+
+ User emails must be unique across the system.
+ "
+ },
+ "parameters": [
+ {
+ // Parameter configuration
+ }
+ ]
+ }
+ }
+ }
+}
+```
+
+The `content` extension supports all Mintlify MDX components and formatting.
+
+### href
+
+Redirect an operation to an external URL or existing documentation page using `x-mint: href`:
+
+```json {14-16}
+{
+ "paths": {
+ "/legacy-endpoint": {
+ "get": {
+ "summary": "Legacy endpoint",
+ "x-mint": {
+ "href": "https://legacy-docs.example.com/api/legacy"
+ }
+ }
+ },
+ "/documented-elsewhere": {
+ "post": {
+ "summary": "Special endpoint",
+ "x-mint": {
+ "href": "/custom-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.
+There are two main approaches for adding endpoint pages into your documentation:
+
+1. **Group-based**: Apply OpenAPI specs at the group level for dedicated API sections.
+2. **Manually-configured**: Set a default OpenAPI spec and selectively include endpoints throughout your navigation.
+
The metadata for the generated pages will have the following default values:
- `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint.
@@ -108,7 +214,11 @@ The metadata for the generated pages will have the following default values:
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.
-### Example with navigation tabs
+### Group-based API pages
+
+Use group-based configuration when you want to dedicate entire sections to auto-generated API documentation.
+
+#### Example with navigation tabs
```json {5}
"navigation": {
@@ -121,7 +231,7 @@ The metadata for the generated pages will have the following default values:
}
```
-### Example with navigation groups
+#### Example with navigation groups
```json {8-11}
"navigation": {
@@ -146,9 +256,93 @@ The metadata for the generated pages will have the following default values:
The directory field is optional. If not specified, the files will be placed in the `api-reference` directory of the docs repo.
+### Manually-configured API pages
+
+Use manually-configured API pages when you want more control over which endpoints appear where in your documentation. This approach allows you to mix API endpoints with other documentation pages.
+
+#### Set a default OpenAPI spec
+
+Configure a default OpenAPI specification at the navigation level to enable automatic endpoint inclusion throughout your documentation:
+
+```json {3, 13-14}
+{
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "tabs": [
+ {
+ "tab": "Getting started",
+ "pages": ["quickstart", "installation"]
+ },
+ {
+ "tab": "API reference",
+ "pages": [
+ "api-overview",
+ "GET /users",
+ "POST /users",
+ "guides/authentication"
+ ]
+ }
+ ]
+ }
+}
+```
+
+When a default OpenAPI spec is set, any navigation entry that matches an OpenAPI operation (using the format `METHOD /path`) will automatically generate an API page for that endpoint.
+
+#### OpenAPI spec inheritance
+
+OpenAPI specifications are inherited through the navigation hierarchy. Child navigation elements automatically use their parent's OpenAPI spec unless they specify their own:
+
+```json {6, 8-9, 14, 16-17}
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "API v1",
+ "openapi": "/specs/v1.json",
+ "pages": [
+ "GET /users",
+ "POST /users"
+ ]
+ },
+ {
+ "tab": "API v2",
+ "openapi": "/specs/v2.json",
+ "pages": [
+ "GET /users",
+ "DELETE /users"
+ ]
+ }
+ ]
+ }
+}
+```
+
+#### Mixed navigation
+
+Combine API endpoints with other pages to create your desired navigation structure:
+
+```json
+{
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "pages": [
+ "introduction",
+ "GET /health",
+ "quickstart",
+ "POST /users",
+ "GET /users/{id}",
+ "advanced-features"
+ ]
+ }
+}
+```
+
## 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, you can also 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
From e78661facff5935a64c09119754eb4f3d8533021 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 13:42:19 -0700
Subject: [PATCH 07/20] fix typo
---
api-playground/overview.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index d786a46a..9dce6b93 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -133,7 +133,7 @@ Both options allow you to:
- Add additional content like examples
- Control playground behavior per page
-The `x-mint` extension is reccomended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.
+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.
From b7982d2112f1b5cc99f4d27dbd5e2bcbde41f043 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 14:38:06 -0700
Subject: [PATCH 08/20] add migration guide
---
api-playground/migrating-from-mdx.mdx | 168 ++++++++++++++++++++++++++
api-playground/overview.mdx | 2 +-
docs.json | 1 +
3 files changed, 170 insertions(+), 1 deletion(-)
create mode 100644 api-playground/migrating-from-mdx.mdx
diff --git a/api-playground/migrating-from-mdx.mdx b/api-playground/migrating-from-mdx.mdx
new file mode 100644
index 00000000..51b2bbfe
--- /dev/null
+++ b/api-playground/migrating-from-mdx.mdx
@@ -0,0 +1,168 @@
+---
+title: "Migrating MDX API pages to OpenAPI navigation"
+sidebarTitle: "Migrating from MDX"
+description: "Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation"
+icon: "arrow-big-right-dash"
+---
+
+If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages.
+
+You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints precisely where you want them in your navigation.
+
+Follow this migration guide to start building your API documentation from your OpenAPI specification with these benefits:
+
+- Automatic page generation from your OpenAPI spec
+- Flexible navigation options
+- Fewer files to maintain
+- Consistent API documentation format
+
+## Before: Individual MDX pages
+
+Previously, you created separate MDX files for each endpoint and referenced them in your navigation:
+
+```json
+{
+ "navigation": [
+ {
+ "group": "API Reference",
+ "pages": [
+ "api/get-users",
+ "api/post-users",
+ "api/delete-users"
+ ]
+ }
+ ]
+}
+```
+
+Each endpoint required its own MDX file with manual configuration and content.
+
+## After: OpenAPI navigation
+
+When you complete the migration, you will reference your OpenAPI specification directly in navigation and automatically generate endpoint pages:
+
+```json
+{
+ "navigation": [
+ {
+ "group": "API Reference",
+ "openapi": "openapi.json"
+ }
+ ]
+}
+```
+
+Or selectively include specific endpoints:
+
+```json
+{
+ "navigation": [
+ {
+ "group": "API Reference",
+ "openapi": "openapi.json",
+ "pages": [
+ "GET /users",
+ "POST /users",
+ "DELETE /users"
+ ]
+ }
+ ]
+}
+```
+
+## Migration steps
+
+
+
+ Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
+
+ For any endpoints that you want to customize the metadata or content, add the `x-mint` extension to the endpoint. See [x-mint extension](/api-playground/openapi-setup#x-mint-extension) for more details.
+
+ For any endpoints that you want to exclude from your documentation, add the `x-hidden` extension to the endpoint.
+
+
+ Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
+
+
+
+
+ Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
+
+ ```json
+ {
+ "navigation": {
+ "openapi": "/path/to/openapi.json",
+ "pages": [
+ "introduction",
+ "GET /health",
+ "quickstart",
+ "POST /users",
+ "GET /users/{id}",
+ "advanced-features"
+ ]
+ }
+ }
+ ```
+
+
+
+
+ After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
+
+
+
+## Navigation patterns
+
+You can customize how your API documentation appears in your navigation.
+
+### Mixed content navigation
+
+Combine automatically generated API pages with other pages:
+
+```json
+{
+ "navigation": [
+ {
+ "group": "API Reference",
+ "openapi": "openapi.json",
+ "pages": [
+ "api/overview",
+ "GET /users",
+ "POST /users",
+ "api/authentication"
+ ]
+ }
+ ]
+}
+```
+
+### Multiple API versions
+
+Organize different API versions using tabs or groups:
+
+```json
+{
+ "navigation": {
+ "tabs": [
+ {
+ "tab": "API v1",
+ "openapi": "specs/v1.json"
+ },
+ {
+ "tab": "API v2",
+ "openapi": "specs/v2.json"
+ }
+ ]
+ }
+}
+```
+
+## When to use individual `MDX` pages
+
+Consider keeping individual `MDX` pages when you need:
+
+- Extensive custom content per endpoint like React components or lengthy examples
+- Unique page layouts
+- Experimental documentation approaches for specific endpoints
+
+For most use cases, OpenAPI navigation provides better maintainability and consistency.
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index 9dce6b93..0baaedc5 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -137,7 +137,7 @@ The `x-mint` extension is recommended so that all of your API documentation is a
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](/api-playground/openapi-setup#x-mint) and [MDX Setup](/api-playground/mdx/configuration).
+For more information, see [x-mint extension](/api-playground/openapi-setup#x-mint-extension) and [MDX Setup](/api-playground/mdx/configuration).
## Further reading
diff --git a/docs.json b/docs.json
index c2e333f1..88564cf5 100644
--- a/docs.json
+++ b/docs.json
@@ -81,6 +81,7 @@
"pages": [
"api-playground/overview",
"api-playground/openapi-setup",
+ "api-playground/migrating-from-mdx",
{
"group": "Customization",
"icon": "wrench",
From 02a5ae69ba63de55591eeb1e3968d5094af17f6b Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Fri, 18 Jul 2025 16:10:35 -0700
Subject: [PATCH 09/20] clarify allowed metadata
---
api-playground/openapi-setup.mdx | 10 ++--------
1 file changed, 2 insertions(+), 8 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index ddfc1e42..956c4826 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -99,7 +99,7 @@ The `x-mint` extension is a custom OpenAPI extension that provides additional co
### Metadata
-Override the default metadata for generated API pages by adding `x-mint: metadata` to any operation:
+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}
{
@@ -126,13 +126,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
}
```
-TODO: what metadata fields are supported?
-
-The `metadata` extension supports:
-- `title`: Override the page title (defaults to operation summary)
-- `description`: Override the page description (defaults to operation description)
-- `og:title`: Override the Open Graph title (defaults to operation summary)
-- `og:description`: Override the Open Graph description (defaults to operation description)
+You cannot override the `openapi`, `version`, or `deprecated` fields.
### Content
From ec90f25bda880908b28690c9916d41214580aef3 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 08:59:20 -0700
Subject: [PATCH 10/20] more precise terms
---
api-playground/openapi-setup.mdx | 8 +++-----
1 file changed, 3 insertions(+), 5 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 956c4826..ac79c84d 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -126,8 +126,6 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
}
```
-You cannot override the `openapi`, `version`, or `deprecated` fields.
-
### Content
Add content before the auto-generated API documentation using `x-mint: content`:
@@ -194,7 +192,7 @@ You can add an `openapi` field to any navigation element in your `docs.json` to
There are two main approaches for adding endpoint pages into your documentation:
-1. **Group-based**: Apply OpenAPI specs at the group level for dedicated API sections.
+1. **Navigation-based**: Apply OpenAPI specs at the navigation level for dedicated API sections.
2. **Manually-configured**: Set a default OpenAPI spec and selectively include endpoints throughout your navigation.
The metadata for the generated pages will have the following default values:
@@ -208,9 +206,9 @@ The metadata for the generated pages will have the following default values:
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.
-### Group-based API pages
+### Navigation-based API pages
-Use group-based configuration when you want to dedicate entire sections to auto-generated API documentation.
+Use navigation-based configuration when you want to dedicate entire sections to auto-generated API documentation.
#### Example with navigation tabs
From bf1d98c6d540d4938d75af49f7bdf72dcbf1c100 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 09:03:02 -0700
Subject: [PATCH 11/20] explain `directory` field
---
api-playground/openapi-setup.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index ac79c84d..bebce38d 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -245,7 +245,7 @@ Use navigation-based configuration when you want to dedicate entire sections to
```
- 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. Use it to specify where the generated API pages are stored in your docs repo. If not specified, the files will be placed in the `api-reference` directory of your repo.
### Manually-configured API pages
From be7ae7567a5f53a82d27598e4032be4f376018c6 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 09:08:56 -0700
Subject: [PATCH 12/20] clarify you can use multiple OpenAPI specs
---
api-playground/openapi-setup.mdx | 17 +++++++++++++----
1 file changed, 13 insertions(+), 4 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index bebce38d..cb0b965f 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -10,6 +10,8 @@ OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0+ d
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.
@@ -188,11 +190,11 @@ When `x-mint: href` is present, the navigation entry will link directly to the s
## 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 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.
-There are two main approaches for adding endpoint pages into your documentation:
+There are two approaches for adding endpoint pages into your documentation:
-1. **Navigation-based**: Apply OpenAPI specs at the navigation level for dedicated API sections.
+1. **Navigation-based**: Reference OpenAPI specs at the navigation level for dedicated API sections.
2. **Manually-configured**: Set a default OpenAPI spec and selectively include endpoints throughout your navigation.
The metadata for the generated pages will have the following default values:
@@ -232,11 +234,18 @@ Use navigation-based configuration when you want to dedicate entire sections to
"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"
+ }
}
]
}
From 215b00dfc428b080ed783f78ab12c021075adda3 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 14:35:33 -0700
Subject: [PATCH 13/20] navigation reviewer feedback
---
navigation.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/navigation.mdx b/navigation.mdx
index 00b97e17..9801c215 100644
--- a/navigation.mdx
+++ b/navigation.mdx
@@ -269,7 +269,7 @@ Set a default OpenAPI specification at any level of your navigation hierarchy. C
```json
{
"navigation": {
- "openapi": "/path/to/openapi.json",
+ "openapi": "/path/to/openapi-v1.json",
"tabs": [
{
"tab": "API v1 reference",
@@ -282,7 +282,7 @@ Set a default OpenAPI specification at any level of your navigation hierarchy. C
},
{
"tab": "API v2 reference",
- "openapi": "/specs/v2.json",
+ "openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /users",
"POST /users"
From e3827939c958aca2fca05bff442cea4f13ebc59e Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 14:45:08 -0700
Subject: [PATCH 14/20] troubleshooting reviewer feedback
---
api-playground/troubleshooting.mdx | 28 +++++-----------------------
1 file changed, 5 insertions(+), 23 deletions(-)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index 68450571..bd63cc5c 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -96,32 +96,14 @@ If your API pages aren't displaying correctly, check these common configuration
1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
-
- 2. **Manual vs automatic inclusion**: If you have a `pages` array in your navigation group, only the operations explicitly listed will appear. Remove the `pages` array to include all operations automatically.
-
- 3. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
+ 2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
+ 3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations will appear in navigation. No other pages will be automatically added. This includes operations that are referenced in child navigation elements.
When combining OpenAPI operations with regular documentation pages in navigation:
- 1. **Default OpenAPI spec required**: You must set a default OpenAPI spec at the navigation level for automatic operation detection:
- ```json
- {
- "navigation": {
- "openapi": "/path/to/openapi.json",
- "pages": [
- "introduction",
- "GET /users",
- "guides/authentication"
- ]
- }
- }
- ```
-
- 2. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation.
-
- 3. **Path resolution**: Navigation entries that don't match OpenAPI operations will be treated as file paths. Ensure your `MDX` files exist at the expected locations.
-
- 4. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
+ 1. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation. If you need to have a file that shares a name with an operation, use the `x-mint` extension for the endpoint to have the href point to a different location.
+ 2. **Path resolution**: Navigation entries that don't match OpenAPI operations will be treated as file paths. Ensure your `MDX` files exist at the expected locations.
+ 3. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
From a9c61cd7663abf0f6e293c960a83a77cc0348252 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 14:50:40 -0700
Subject: [PATCH 15/20] overview reviewer feedback
---
api-playground/overview.mdx | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index 0baaedc5..dd25a169 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -35,7 +35,7 @@ We recommend generating your API playground from an OpenAPI specification. See [
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.
- 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.
+ This example generates a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
```json
{
@@ -50,7 +50,7 @@ We recommend generating your API playground from an OpenAPI specification. See [
To generate pages for only specific endpoints, list the endpoints in the `pages` property of the navigation element.
- In this example, only pages for the `GET /users` and `POST /users` endpoints will be generated regardless of what other endpoints are specified in `openapi.json`.
+ This example generates pages for only the `GET /users` and `POST /users` endpoints. To genereate other endpoint pages, add additional endpoints to the `pages` array.
```json
{
From 3b09774be423c54d8e07cb91526101005b2ac2b5 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 15:08:17 -0700
Subject: [PATCH 16/20] setup reviewer feedback
---
api-playground/openapi-setup.mdx | 35 +++++++++++++++-----------------
1 file changed, 16 insertions(+), 19 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index cb0b965f..17960d51 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -139,12 +139,7 @@ Add content before the auto-generated API documentation using `x-mint: content`:
"post": {
"summary": "Create user",
"x-mint": {
- "content": "## Prerequisites
- This endpoint requires admin privileges and has rate limiting.
-
-
- User emails must be unique across the system.
- "
+ "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\nUser emails must be unique across the system."
},
"parameters": [
{
@@ -161,16 +156,16 @@ The `content` extension supports all Mintlify MDX components and formatting.
### href
-Redirect an operation to an external URL or existing documentation page using `x-mint: href`:
+Change the URL of the endpoint page in your docs using `x-mint: href`:
-```json {14-16}
+```json {6-8, 14-16}
{
"paths": {
"/legacy-endpoint": {
"get": {
"summary": "Legacy endpoint",
"x-mint": {
- "href": "https://legacy-docs.example.com/api/legacy"
+ "href": "/deprecated-endpoints/legacy-endpoint"
}
}
},
@@ -178,7 +173,7 @@ Redirect an operation to an external URL or existing documentation page using `x
"post": {
"summary": "Special endpoint",
"x-mint": {
- "href": "/custom-guides/special-endpoint-guide"
+ "href": "/guides/special-endpoint-guide"
}
}
}
@@ -194,7 +189,7 @@ Add an `openapi` field to any navigation element in your `docs.json` to auto-pop
There are two approaches for adding endpoint pages into your documentation:
-1. **Navigation-based**: Reference OpenAPI specs at the navigation level for dedicated API sections.
+1. **Fully auto-generated**: Reference OpenAPI specs at the navigation level for dedicated API sections.
2. **Manually-configured**: Set a default OpenAPI spec and selectively include endpoints throughout your navigation.
The metadata for the generated pages will have the following default values:
@@ -208,9 +203,9 @@ The metadata for the generated pages will have the following default values:
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.
-### Navigation-based API pages
+### Fully auto-generated API pages
-Use navigation-based configuration when you want to dedicate entire sections to auto-generated API documentation.
+Use a fully auto-generated configuration when you want to dedicate entire sections to auto-generated API documentation.
#### Example with navigation tabs
@@ -294,24 +289,26 @@ When a default OpenAPI spec is set, any navigation entry that matches an OpenAPI
OpenAPI specifications are inherited through the navigation hierarchy. Child navigation elements automatically use their parent's OpenAPI spec unless they specify their own:
-```json {6, 8-9, 14, 16-17}
+```json {3, 10-11, 16, 18-19}
{
"navigation": {
+ "openapi": "/path/to/openapi-v1.json",
"tabs": [
{
- "tab": "API v1",
- "openapi": "/specs/v1.json",
+ "tab": "API v1 reference",
"pages": [
+ "overview",
+ "authentication",
"GET /users",
"POST /users"
]
},
{
- "tab": "API v2",
- "openapi": "/specs/v2.json",
+ "tab": "API v2 reference",
+ "openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /users",
- "DELETE /users"
+ "POST /users"
]
}
]
From 63f6480320d759850f354bf37ff6d634ff868a55 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 16:51:50 -0700
Subject: [PATCH 17/20] fewer things to troubleshoot
---
api-playground/troubleshooting.mdx | 9 ++-------
1 file changed, 2 insertions(+), 7 deletions(-)
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index bd63cc5c..0ba99fdc 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -84,14 +84,9 @@ If your API pages aren't displaying correctly, check these common configuration
}
```
- 2. **Incorrect operation format**: Navigation entries must exactly match the HTTP method and path in your OpenAPI spec:
- - Correct: `"GET /users/{id}"`
- - Incorrect: `"get /users/{id}"` (wrong case)
- - Incorrect: `"GET /users/{id}/"` (extra trailing slash)
+ 2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
- 3. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
-
- 4. **Validation issues**: Use `mint openapi-check ` to verify your OpenAPI document is valid.
+ 3. **Validation issues**: Use `mint openapi-check ` to verify your OpenAPI document is valid.
From 7fe056263ce35c7eef927ad436ea24272c058c72 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 21 Jul 2025 17:34:52 -0700
Subject: [PATCH 18/20] update auto-populate API pages section
---
api-playground/openapi-setup.mdx | 65 +++++++++++++++++---------------
1 file changed, 34 insertions(+), 31 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 17960d51..b64e6e00 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -185,29 +185,29 @@ When `x-mint: href` is present, the navigation entry will link directly to the s
## Auto-populate API pages
-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. You can control where these pages appear in your navigation structure, as dedicated API sections or with other pages.
-There are two approaches for adding endpoint pages into your documentation:
-
-1. **Fully auto-generated**: Reference OpenAPI specs at the navigation level for dedicated API sections.
-2. **Manually-configured**: Set a default OpenAPI spec and selectively include endpoints throughout your navigation.
+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.
- 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.
-### Fully auto-generated API pages
+There are two approaches for adding endpoint pages into your documentation:
-Use a fully auto-generated configuration when you want to dedicate entire sections to auto-generated API 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.
-#### Example with navigation tabs
+### 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": {
@@ -220,9 +220,9 @@ Use a fully auto-generated configuration when you want to dedicate entire sectio
}
```
-#### Example with navigation groups
+You can use multiple OpenAPI specifications in different navigation sections:
-```json {8-11}
+```json {8-11, 15-18}
"navigation": {
"tabs": [
{
@@ -249,16 +249,16 @@ Use a fully auto-generated configuration when you want to dedicate entire sectio
```
- The `directory` field is optional. Use it to specify where the generated API pages are stored in your docs repo. If not specified, the files will be placed in the `api-reference` directory of your 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.
-### Manually-configured API pages
+### Selective endpoints
-Use manually-configured API pages when you want more control over which endpoints appear where in your documentation. This approach allows you to mix API endpoints with other documentation pages.
+When you want more control over which endpoints appear where in your documentation, you can reference specific endpoints in your navigation. This approach allows you to mix API endpoints with other documentation pages.
#### Set a default OpenAPI spec
-Configure a default OpenAPI specification at the navigation level to enable automatic endpoint inclusion throughout your documentation:
+Configure a default OpenAPI specification at the navigation level. This enables automatic endpoint inclusion throughout your documentation:
```json {3, 13-14}
{
@@ -283,11 +283,11 @@ Configure a default OpenAPI specification at the navigation level to enable auto
}
```
-When a default OpenAPI spec is set, any navigation entry that matches an OpenAPI operation (using the format `METHOD /path`) will automatically generate an API page for that endpoint.
+Any page entry matching the format `METHOD /path` will generate an API page for that endpoint using the default OpenAPI spec.
#### OpenAPI spec inheritance
-OpenAPI specifications are inherited through the navigation hierarchy. Child navigation elements automatically use their parent's OpenAPI spec unless they specify their own:
+OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own:
```json {3, 10-11, 16, 18-19}
{
@@ -316,26 +316,25 @@ OpenAPI specifications are inherited through the navigation hierarchy. Child nav
}
```
-#### Mixed navigation
+#### Individual endpoints
-Combine API endpoints with other pages to create your desired navigation structure:
+Reference specific endpoints without setting a default OpenAPI specification by including the file path:
-```json
+```json {6-7}
{
"navigation": {
- "openapi": "/path/to/openapi.json",
"pages": [
"introduction",
- "GET /health",
- "quickstart",
- "POST /users",
- "GET /users/{id}",
- "advanced-features"
+ "user-guides",
+ "/path/to/openapi-v1.json POST /users",
+ "/path/to/openapi-v2.json GET /orders"
]
}
}
```
+This approach is useful when you need individual endpoints from different specs or only want to include select endpoints.
+
## Create `MDX` files for API pages
For control over individual endpoint pages, you can also 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.
@@ -350,6 +349,10 @@ When you reference an OpenAPI operation this way, the name, description, paramet
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.
+
+ 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.
+
+
If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
From b56e3f264c815e950bde8ddd21090265eae4d68d Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 30 Jul 2025 18:00:38 -0700
Subject: [PATCH 19/20] remove navigation content
---
api-playground/mdx/configuration.mdx | 2 +-
api-playground/migrating-from-mdx.mdx | 168 --------------------------
api-playground/openapi-setup.mdx | 89 +-------------
api-playground/overview.mdx | 19 ---
api-playground/troubleshooting.mdx | 30 -----
docs.json | 1 -
navigation.mdx | 37 ------
7 files changed, 3 insertions(+), 343 deletions(-)
delete mode 100644 api-playground/migrating-from-mdx.mdx
diff --git a/api-playground/mdx/configuration.mdx b/api-playground/mdx/configuration.mdx
index c7eb6a46..76f14c39 100644
--- a/api-playground/mdx/configuration.mdx
+++ b/api-playground/mdx/configuration.mdx
@@ -3,7 +3,7 @@ title: 'MDX setup'
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 projects because it is more maintainable and feature-rich. However, creating `MDX` pages for an API can be useful to document small APIs or for prototyping.
+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 `` to define parameters. From these definitions, Mintlify generates interactive API playgrounds, request examples, and response examples.
diff --git a/api-playground/migrating-from-mdx.mdx b/api-playground/migrating-from-mdx.mdx
deleted file mode 100644
index 51b2bbfe..00000000
--- a/api-playground/migrating-from-mdx.mdx
+++ /dev/null
@@ -1,168 +0,0 @@
----
-title: "Migrating MDX API pages to OpenAPI navigation"
-sidebarTitle: "Migrating from MDX"
-description: "Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation"
-icon: "arrow-big-right-dash"
----
-
-If you are currently using individual `MDX` pages for your API endpoints, you can migrate to autogenerating pages from your OpenAPI specification while retaining the customizability of individual pages.
-
-You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints precisely where you want them in your navigation.
-
-Follow this migration guide to start building your API documentation from your OpenAPI specification with these benefits:
-
-- Automatic page generation from your OpenAPI spec
-- Flexible navigation options
-- Fewer files to maintain
-- Consistent API documentation format
-
-## Before: Individual MDX pages
-
-Previously, you created separate MDX files for each endpoint and referenced them in your navigation:
-
-```json
-{
- "navigation": [
- {
- "group": "API Reference",
- "pages": [
- "api/get-users",
- "api/post-users",
- "api/delete-users"
- ]
- }
- ]
-}
-```
-
-Each endpoint required its own MDX file with manual configuration and content.
-
-## After: OpenAPI navigation
-
-When you complete the migration, you will reference your OpenAPI specification directly in navigation and automatically generate endpoint pages:
-
-```json
-{
- "navigation": [
- {
- "group": "API Reference",
- "openapi": "openapi.json"
- }
- ]
-}
-```
-
-Or selectively include specific endpoints:
-
-```json
-{
- "navigation": [
- {
- "group": "API Reference",
- "openapi": "openapi.json",
- "pages": [
- "GET /users",
- "POST /users",
- "DELETE /users"
- ]
- }
- ]
-}
-```
-
-## Migration steps
-
-
-
- Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
-
- For any endpoints that you want to customize the metadata or content, add the `x-mint` extension to the endpoint. See [x-mint extension](/api-playground/openapi-setup#x-mint-extension) for more details.
-
- For any endpoints that you want to exclude from your documentation, add the `x-hidden` extension to the endpoint.
-
-
- Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
-
-
-
-
- Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
-
- ```json
- {
- "navigation": {
- "openapi": "/path/to/openapi.json",
- "pages": [
- "introduction",
- "GET /health",
- "quickstart",
- "POST /users",
- "GET /users/{id}",
- "advanced-features"
- ]
- }
- }
- ```
-
-
-
-
- After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
-
-
-
-## Navigation patterns
-
-You can customize how your API documentation appears in your navigation.
-
-### Mixed content navigation
-
-Combine automatically generated API pages with other pages:
-
-```json
-{
- "navigation": [
- {
- "group": "API Reference",
- "openapi": "openapi.json",
- "pages": [
- "api/overview",
- "GET /users",
- "POST /users",
- "api/authentication"
- ]
- }
- ]
-}
-```
-
-### Multiple API versions
-
-Organize different API versions using tabs or groups:
-
-```json
-{
- "navigation": {
- "tabs": [
- {
- "tab": "API v1",
- "openapi": "specs/v1.json"
- },
- {
- "tab": "API v2",
- "openapi": "specs/v2.json"
- }
- ]
- }
-}
-```
-
-## When to use individual `MDX` pages
-
-Consider keeping individual `MDX` pages when you need:
-
-- Extensive custom content per endpoint like React components or lengthy examples
-- Unique page layouts
-- Experimental documentation approaches for specific endpoints
-
-For most use cases, OpenAPI navigation provides better maintainability and consistency.
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index b64e6e00..81a4e955 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -185,9 +185,7 @@ When `x-mint: href` is present, the navigation entry will link directly to the s
## Auto-populate API pages
-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.
+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.
Generated endpoint pages have these default metadata values:
@@ -252,92 +250,9 @@ You can use multiple OpenAPI specifications in different navigation sections:
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.
-### Selective endpoints
-
-When you want more control over which endpoints appear where in your documentation, you can reference specific endpoints in your navigation. This approach allows you to mix API endpoints with other documentation pages.
-
-#### Set a default OpenAPI spec
-
-Configure a default OpenAPI specification at the navigation level. This enables automatic endpoint inclusion throughout your documentation:
-
-```json {3, 13-14}
-{
- "navigation": {
- "openapi": "/path/to/openapi.json",
- "tabs": [
- {
- "tab": "Getting started",
- "pages": ["quickstart", "installation"]
- },
- {
- "tab": "API reference",
- "pages": [
- "api-overview",
- "GET /users",
- "POST /users",
- "guides/authentication"
- ]
- }
- ]
- }
-}
-```
-
-Any page entry matching the format `METHOD /path` will generate an API page for that endpoint using the default OpenAPI spec.
-
-#### 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, 10-11, 16, 18-19}
-{
- "navigation": {
- "openapi": "/path/to/openapi-v1.json",
- "tabs": [
- {
- "tab": "API v1 reference",
- "pages": [
- "overview",
- "authentication",
- "GET /users",
- "POST /users"
- ]
- },
- {
- "tab": "API v2 reference",
- "openapi": "/path/to/openapi-v2.json",
- "pages": [
- "GET /users",
- "POST /users"
- ]
- }
- ]
- }
-}
-```
-
-#### Individual endpoints
-
-Reference specific endpoints without setting a default OpenAPI specification by including the file path:
-
-```json {6-7}
-{
- "navigation": {
- "pages": [
- "introduction",
- "user-guides",
- "/path/to/openapi-v1.json POST /users",
- "/path/to/openapi-v2.json GET /orders"
- ]
- }
-}
-```
-
-This approach is useful when you need individual endpoints from different specs or only want to include select endpoints.
-
## Create `MDX` files for API pages
-For control over individual endpoint pages, you can also 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.
+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).
diff --git a/api-playground/overview.mdx b/api-playground/overview.mdx
index dd25a169..9d22a05e 100644
--- a/api-playground/overview.mdx
+++ b/api-playground/overview.mdx
@@ -48,25 +48,6 @@ We recommend generating your API playground from an OpenAPI specification. See [
}
```
- To generate pages for only specific endpoints, list the endpoints in the `pages` property of the navigation element.
-
- This example generates pages for only the `GET /users` and `POST /users` endpoints. To genereate other endpoint pages, add additional endpoints to the `pages` array.
-
- ```json
- {
- "navigation": [
- {
- "group": "API reference",
- "openapi": "openapi.json",
- "pages": [
- "GET /users",
- "POST /users"
- ]
- }
- ]
- }
- ```
-
diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx
index 0ba99fdc..8af5a94a 100644
--- a/api-playground/troubleshooting.mdx
+++ b/api-playground/troubleshooting.mdx
@@ -71,34 +71,4 @@ If your API pages aren't displaying correctly, check these common configuration
Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure Mintlify to send requests directly to your backend with the `api.playground.proxy` setting in the `docs.json`, as described in the [settings documentation](/settings#param-proxy). When using this configuration, you will need to configure CORS on your server since requests will come directly from users' browsers rather than through your proxy.
-
- If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
-
- 1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set at the navigation level:
- ```json
- {
- "navigation": {
- "openapi": "/path/to/openapi.json",
- "pages": ["GET /users", "POST /users"]
- }
- }
- ```
-
- 2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
-
- 3. **Validation issues**: Use `mint openapi-check ` to verify your OpenAPI document is valid.
-
-
-
- 1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
- 2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
- 3. **Manual vs automatic inclusion**: If you reference any endpoints from an OpenAPI spec, only the explicitly referenced operations will appear in navigation. No other pages will be automatically added. This includes operations that are referenced in child navigation elements.
-
-
- When combining OpenAPI operations with regular documentation pages in navigation:
-
- 1. **File conflicts**: You cannot have both an `MDX` file and a navigation entry for the same operation. For example, if you have `get-users.mdx`, do not also include `"GET /users"` in your navigation. If you need to have a file that shares a name with an operation, use the `x-mint` extension for the endpoint to have the href point to a different location.
- 2. **Path resolution**: Navigation entries that don't match OpenAPI operations will be treated as file paths. Ensure your `MDX` files exist at the expected locations.
- 3. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
-
diff --git a/docs.json b/docs.json
index 88564cf5..c2e333f1 100644
--- a/docs.json
+++ b/docs.json
@@ -81,7 +81,6 @@
"pages": [
"api-playground/overview",
"api-playground/openapi-setup",
- "api-playground/migrating-from-mdx",
{
"group": "Customization",
"icon": "wrench",
diff --git a/navigation.mdx b/navigation.mdx
index 9801c215..5e27a44d 100644
--- a/navigation.mdx
+++ b/navigation.mdx
@@ -260,43 +260,6 @@ While not required, we also recommend that you set an icon for each dropdown ite
---
-## OpenAPI
-
-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.
-
-```json
-{
- "navigation": {
- "openapi": "/path/to/openapi-v1.json",
- "tabs": [
- {
- "tab": "API v1 reference",
- "pages": [
- "overview",
- "authentication",
- "GET /users",
- "POST /users"
- ]
- },
- {
- "tab": "API v2 reference",
- "openapi": "/path/to/openapi-v2.json",
- "pages": [
- "GET /users",
- "POST /users"
- ]
- }
- ]
- }
-}
-```
-
-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.
From c45f385ab4eab058ec334e3cfbcc5d7a64d49d66 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Tue, 5 Aug 2025 12:08:55 -0700
Subject: [PATCH 20/20] reviewer feedback
---
api-playground/openapi-setup.mdx | 2 --
1 file changed, 2 deletions(-)
diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 81a4e955..282ced94 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -181,8 +181,6 @@ Change the URL of the endpoint page in your docs using `x-mint: href`:
}
```
-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
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.