Skip to content

Commit 60590ec

Browse files
handotdevhandotdev
committed
Merge branch 'main' of https://github.com/mintlify/docs 
2 parents 6412e59 + 6ad6192 commit 60590ec

File tree

13 files changed

+441
-75
lines changed

13 files changed

+441
-75
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: 122 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@ We recommend the following resources to learn about and construct your OpenAPI d
2222
- [The Mint CLI](https://www.npmjs.com/package/mint) to validate your OpenAPI document with the command: `mint openapi-check <openapiFilenameOrUrl>`.
2323

2424
<Note>
25-
Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, see [Migrating from OpenAPI 3.0 to 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) in the OpenAPI blog.
25+
Swagger's OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information
26+
is applicable to v3.1. For more information on the differences between v3.0
27+
and v3.1, see [Migrating from OpenAPI 3.0 to
28+
3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
29+
in the OpenAPI blog.
2630
</Note>
2731

2832
### Specifying the URL for your API
@@ -53,34 +57,34 @@ To enable authentication in your API documentation and playground, configure the
5357
<Step title="Define your authentication method.">
5458
Add a `securitySchemes` field to define how users authenticate.
5559

56-
This example shows a configuration for bearer authentication.
60+
This example shows a configuration for bearer authentication.
5761

58-
```json
59-
{
60-
"components": {
61-
"securitySchemes": {
62-
"bearerAuth": {
62+
```json
63+
{
64+
"components": {
65+
"securitySchemes": {
66+
"bearerAuth": {
6367
"type": "http",
6468
"scheme": "bearer"
65-
}
6669
}
6770
}
6871
}
69-
```
72+
}
73+
```
7074

7175
</Step>
7276
<Step title="Apply authentication to your endpoints.">
7377
Add a `security` field to require authentication.
7478

75-
```json
76-
{
77-
"security": [
78-
{
79-
"bearerAuth": []
80-
}
81-
]
82-
}
83-
```
79+
```json
80+
{
81+
"security": [
82+
{
83+
"bearerAuth": []
84+
}
85+
]
86+
}
87+
```
8488

8589
</Step>
8690
</Steps>
@@ -114,7 +118,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
114118
"metadata": {
115119
"title": "List all users",
116120
"description": "Fetch paginated user data with filtering options",
117-
"og:title": "Display a list of users",
121+
"og:title": "Display a list of users"
118122
}
119123
},
120124
"parameters": [
@@ -132,7 +136,7 @@ Override the default metadata for generated API pages by adding `x-mint: metadat
132136

133137
Add content before the auto-generated API documentation using `x-mint: content`:
134138

135-
```json {6-13}
139+
```json {6-8}
136140
{
137141
"paths": {
138142
"/users": {
@@ -181,6 +185,8 @@ Change the URL of the endpoint page in your docs using `x-mint: href`:
181185
}
182186
```
183187

188+
When `x-mint: href` is present, the navigation entry will link directly to the specified URL instead of generating an API page.
189+
184190
### MCP
185191

186192
Expose endpoints as MCP tools by using `x-mint: mcp`:
@@ -209,7 +215,9 @@ Expose endpoints as MCP tools by using `x-mint: mcp`:
209215

210216
## Auto-populate API pages
211217

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.
218+
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.
219+
220+
The `openapi` field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.
213221

214222
Generated endpoint pages have these default metadata values:
215223

@@ -219,17 +227,19 @@ Generated endpoint pages have these default metadata values:
219227
- `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.
220228

221229
<Tip>
222-
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.
230+
To exclude specific endpoints from your auto-generated API pages, add the
231+
[x-hidden](/api-playground/customization/managing-page-visibility#x-hidden)
232+
property to the operation in your OpenAPI spec.
223233
</Tip>
224234

225235
There are two approaches for adding endpoint pages into your documentation:
226236

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

230240
### Dedicated API sections
231241

232-
Generate complete API sections by adding an `openapi` field to any navigation element. All endpoints in the specification will be included:
242+
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:
233243

234244
```json {5}
235245
"navigation": {
@@ -271,9 +281,87 @@ You can use multiple OpenAPI specifications in different navigation sections:
271281
```
272282

273283
<Note>
274-
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.
284+
The `directory` field is optional and specifies where generated API pages are
285+
stored in your docs repo. If not specified, defaults to the `api-reference`
286+
directory of your repo.
275287
</Note>
276288

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

279367
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.
@@ -289,7 +377,9 @@ When you reference an OpenAPI operation this way, the name, description, paramet
289377
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.
290378

291379
<Note>
292-
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.
380+
This approach works regardless of whether you have set a default OpenAPI spec
381+
in your navigation. You can reference any endpoint from any OpenAPI spec by
382+
including the file path in the frontmatter.
293383
</Note>
294384

295385
If you want to reference an external OpenAPI file, add the file's URL to your `docs.json`.
@@ -319,7 +409,9 @@ version: "version-string" (not required)
319409
</CodeGroup>
320410

321411
<Note>
322-
The method and path must exactly match the definition in your OpenAPI specification. If the endpoint doesn't exist in the OpenAPI file, the page will be empty.
412+
The method and path must exactly match the definition in your OpenAPI
413+
specification. If the endpoint doesn't exist in the OpenAPI file, the page
414+
will be empty.
323415
</Note>
324416

325417
### Autogenerate `MDX` files
@@ -348,6 +440,7 @@ The scraper generates:
348440
```
349441

350442
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.
443+
351444
</Step>
352445
</Steps>
353446

@@ -363,7 +456,6 @@ openapi-schema: OrderItem
363456
---
364457
```
365458

366-
367459
```mdx Format
368460
---
369461
openapi-schema: "schema-key"
@@ -395,5 +487,6 @@ openapi: "path/to/openapi-file webhook example-webhook-name"
395487
```
396488

397489
<Note>
398-
The webhook name must exactly match the key defined in your OpenAPI specification's `webhooks` field.
490+
The webhook name must exactly match the key defined in your OpenAPI
491+
specification's `webhooks` field.
399492
</Note>

0 commit comments

Comments
 (0)