Skip to content

Commit a6feb60

Browse files
mycho2003ethanpalm
mycho2003
and
ethanpalm
authored
Openapi nav updates (#1008)
* add troubleshooting info * update conceptual info in MDX setup * add OpenAPI section to navigation page * update overview steps * Update info about customizing endpoint pages * update setup information * fix typo * add migration guide * clarify allowed metadata * more precise terms * explain `directory` field * clarify you can use multiple OpenAPI specs * navigation reviewer feedback * troubleshooting reviewer feedback * overview reviewer feedback * setup reviewer feedback * fewer things to troubleshoot * update auto-populate API pages section * update JSON example * update default OpenAPI spec example * update spec inheritance example * replace example * fix overview JSON examples * update navigation example * update troubleshooting example * Update openapi-setup.mdx * Update migration guide * update JSON examples --------- Co-authored-by: Ethan Palm <[email protected]>
1 parent 4a7e3ae commit a6feb60

File tree

7 files changed

+292
-7
lines changed

7 files changed

+292
-7
lines changed

‎api-playground/mdx/configuration.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'MDX setup'
33
description: 'Generate docs pages for your API endpoints using `MDX`'
44
---
55

6-
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.
6+
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.
77

88
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.
99

‎api-playground/migrating-from-mdx.mdx

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "Migrating MDX API pages to OpenAPI navigation"
3+
sidebarTitle: "Migrating from MDX"
4+
description: "Update from individual MDX endpoint pages to automated OpenAPI generation with flexible navigation"
5+
icon: "arrow-big-right-dash"
6+
---
7+
8+
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. This can help you reduce the number of files you need to maintain and improve the consistency of your API documentation.
9+
10+
You can define metadata and content for each endpoint in your OpenAPI specification and organize endpoints where you want them in your navigation.
11+
12+
## Migration steps
13+
14+
<Steps>
15+
<Step title="Prepare your OpenAPI specification.">
16+
Ensure your OpenAPI specification is valid and includes all endpoints you want to document.
17+
18+
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.
19+
20+
For any endpoints that you want to exclude from your documentation, add the `x-hidden` extension to the endpoint.
21+
22+
<Info>
23+
Validate your OpenAPI file using the [Swagger Editor](https://editor.swagger.io/) or [Mint CLI](https://www.npmjs.com/package/mint).
24+
</Info>
25+
</Step>
26+
27+
<Step title="Update your navigation structure.">
28+
Replace `MDX` page references with OpenAPI endpoints in your `docs.json`.
29+
30+
```json
31+
"navigation": {
32+
"groups": [
33+
{
34+
"group": "API Reference",
35+
"openapi": "/path/to/openapi.json",
36+
"pages": [
37+
"overview",
38+
"authentication",
39+
"introduction",
40+
"GET /health",
41+
"quickstart",
42+
"POST /users",
43+
"GET /users/{id}",
44+
"advanced-features"
45+
]
46+
}
47+
]
48+
}
49+
```
50+
51+
</Step>
52+
53+
<Step title="Remove old MDX files.">
54+
After verifying your new navigation works correctly, remove the `MDX` endpoint files that you no longer need.
55+
</Step>
56+
</Steps>
57+
58+
## Navigation patterns
59+
60+
You can customize how your API documentation appears in your navigation.
61+
62+
### Mixed content navigation
63+
64+
Combine automatically generated API pages with other pages:
65+
66+
```json
67+
"navigation": {
68+
"groups": [
69+
{
70+
"group": "API Reference",
71+
"openapi": "openapi.json",
72+
"pages": [
73+
"api/overview",
74+
"GET /users",
75+
"POST /users",
76+
"api/authentication"
77+
]
78+
}
79+
]
80+
}
81+
```
82+
83+
### Multiple API versions
84+
85+
Organize different API versions using tabs or groups:
86+
87+
```json
88+
"navigation": {
89+
"tabs": [
90+
{
91+
"tab": "API v1",
92+
"openapi": "specs/v1.json"
93+
},
94+
{
95+
"tab": "API v2",
96+
"openapi": "specs/v2.json"
97+
}
98+
]
99+
}
100+
```
101+
102+
## When to use individual `MDX` pages
103+
104+
Consider keeping individual `MDX` pages when you need:
105+
106+
- Extensive custom content per endpoint like React components or lengthy examples.
107+
- Unique page layouts.
108+
- Experimental documentation approaches for specific endpoints.
109+
110+
For most use cases, OpenAPI navigation provides better maintainability and consistency.

‎api-playground/openapi-setup.mdx

Lines changed: 83 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,8 @@ Change the URL of the endpoint page in your docs using `x-mint: href`:
181181
}
182182
```
183183

184+
When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
185+
184186
### MCP
185187

186188
Expose endpoints as MCP tools by using `x-mint: mcp`:
@@ -209,7 +211,9 @@ Expose endpoints as MCP tools by using `x-mint: mcp`:
209211

210212
## Auto-populate API pages
211213

212-
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.
214+
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.
215+
216+
The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.
213217

214218
Generated endpoint pages have these default metadata values:
215219

@@ -224,12 +228,12 @@ Generated endpoint pages have these default metadata values:
224228

225229
There are two approaches for adding endpoint pages into your documentation:
226230

227-
1. **Dedicated API sections**: Reference OpenAPI specs at the navigation level for dedicated API sections.
231+
1. **Dedicated API sections**: Reference OpenAPI specs in navigation elements for dedicated API sections.
228232
2. **Selective endpoints**: Reference specific endpoints in your navigation alongside other pages.
229233

230234
### Dedicated API sections
231235

232-
Generate complete API sections by adding an `openapi` field to any navigation element. All endpoints in the specification will be included:
236+
Generate dedicated API sections by adding an `openapi` field to a navigation element and no other pages. All endpoints in the specification will be included:
233237

234238
```json {5}
235239
"navigation": {
@@ -274,6 +278,82 @@ You can use multiple OpenAPI specifications in different navigation sections:
274278
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.
275279
</Note>
276280

281+
### Selective endpoints
282+
283+
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.
284+
285+
#### Set a default OpenAPI spec
286+
287+
Configure a default OpenAPI specification for a navigation element. Then reference specific endpoints in the `pages` field:
288+
289+
```json {12, 15-16}
290+
"navigation": {
291+
"tabs": [
292+
{
293+
"tab": "Getting started",
294+
"pages": [
295+
"quickstart",
296+
"installation"
297+
]
298+
},
299+
{
300+
"tab": "API reference",
301+
"openapi": "/path/to/openapi.json",
302+
"pages": [
303+
"api-overview",
304+
"GET /users",
305+
"POST /users",
306+
"guides/authentication"
307+
]
308+
}
309+
]
310+
}
311+
```
312+
313+
Any page entry matching the format `METHOD /path` will generate an API page for that endpoint using the default OpenAPI spec.
314+
315+
#### OpenAPI spec inheritance
316+
317+
OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent's OpenAPI specification unless they define their own:
318+
319+
```json {5, 12-13, 18, 20-21}
320+
{
321+
"group": "API reference",
322+
"openapi": "/path/to/openapi-v1.json",
323+
"pages": [
324+
"overview",
325+
"authentication",
326+
"GET /users",
327+
"POST /users",
328+
{
329+
"group": "Orders",
330+
"openapi": "/path/to/openapi-v2.json",
331+
"pages": [
332+
"GET /orders",
333+
"POST /orders"
334+
]
335+
}
336+
]
337+
},
338+
```
339+
340+
#### Individual endpoints
341+
342+
Reference specific endpoints without setting a default OpenAPI specification by including the file path:
343+
344+
```json {5-6}
345+
"navigation": {
346+
"pages": [
347+
"introduction",
348+
"user-guides",
349+
"/path/to/openapi-v1.json POST /users",
350+
"/path/to/openapi-v2.json GET /orders"
351+
]
352+
}
353+
```
354+
355+
This approach is useful when you need individual endpoints from different specs or only want to include select endpoints.
356+
277357
## Create `MDX` files for API pages
278358

279359
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.

‎api-playground/overview.mdx

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,30 @@ We recommend generating your API playground from an OpenAPI specification. See [
3838
This example generates a page for each endpoint specified in `openapi.json` and organize them under the "API reference" group in your navigation.
3939

4040
```json
41-
{
42-
"navigation": [
41+
"navigation": {
42+
"groups": [
43+
{
44+
"group": "API reference",
45+
"openapi": "openapi.json"
46+
}
47+
]
48+
}
49+
```
50+
51+
To generate pages for only specific endpoints, list the endpoints in the `pages` property of the navigation element.
52+
53+
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.
54+
55+
```json
56+
"navigation": {
57+
"groups": [
4358
{
4459
"group": "API reference",
45-
"openapi": "openapi.json"
60+
"openapi": "openapi.json",
61+
"pages": [
62+
"GET /users",
63+
"POST /users"
64+
]
4665
}
4766
]
4867
}

‎api-playground/troubleshooting.mdx

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,4 +71,40 @@ If your API pages aren't displaying correctly, check these common configuration
7171

7272
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.
7373
</Accordion>
74+
<Accordion title="OpenAPI navigation entries are not generating pages">
75+
If you are using an OpenAPI navigation configuration, but the pages aren't generating, check these common issues:
76+
77+
1. **Missing default OpenAPI spec**: Ensure you have an `openapi` field set for the navigation element:
78+
```json {5}
79+
"navigation": {
80+
"groups": [
81+
{
82+
"group": "API reference",
83+
"openapi": "/path/to/openapi.json",
84+
"pages": [
85+
"GET /users",
86+
"POST /users"
87+
]
88+
}
89+
]
90+
}
91+
```
92+
93+
2. **OpenAPI spec inheritance**: If using nested navigation, ensure child groups inherit the correct OpenAPI spec or specify their own.
94+
95+
3. **Validation issues**: Use `mint openapi-check <path-to-openapi-file>` to verify your OpenAPI document is valid.
96+
</Accordion>
97+
<Accordion title="Some OpenAPI operations appear in navigation but others don't">
98+
99+
1. **Hidden operations**: Operations marked with `x-hidden: true` in your OpenAPI spec won't appear in auto-generated navigation.
100+
2. **Invalid operations**: Operations with validation errors in the OpenAPI spec may be skipped. Check your OpenAPI document for syntax errors.
101+
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.
102+
</Accordion>
103+
<Accordion title="Mixed navigation (OpenAPI and MDX pages) not working correctly">
104+
When combining OpenAPI operations with regular documentation pages in navigation:
105+
106+
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.
107+
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.
108+
3. **Case sensitivity**: OpenAPI operation matching is case-sensitive. Ensure HTTP methods are uppercase in navigation entries.
109+
</Accordion>
74110
</AccordionGroup>

‎docs.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@
8383
"pages": [
8484
"api-playground/overview",
8585
"api-playground/openapi-setup",
86+
"api-playground/migrating-from-mdx",
8687
{
8788
"group": "Customization",
8889
"icon": "wrench",

‎navigation.mdx

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,45 @@ While not required, we also recommend that you set an icon for each dropdown ite
296296
}
297297
```
298298

299+
---
300+
301+
## OpenAPI
302+
303+
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.
304+
305+
Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements will inherit this specification unless they define their own specification.
306+
307+
```json
308+
{
309+
"navigation": {
310+
"groups": [
311+
{
312+
"group": "API reference",
313+
"openapi": "/path/to/openapi-v1.json",
314+
"pages": [
315+
"overview",
316+
"authentication",
317+
"GET /users",
318+
"POST /users",
319+
{
320+
"group": "Products",
321+
"openapi": "/path/to/openapi-v2.json",
322+
"pages": [
323+
"GET /products",
324+
"POST /products"
325+
]
326+
}
327+
]
328+
}
329+
]
330+
}
331+
}
332+
```
333+
334+
For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
335+
336+
---
337+
299338
## Versions
300339

301340
Partition your navigation into different versions.

0 commit comments

Comments
 (0)