Skip to content

Commit e0099b1

Browse files
mintlify-development[bot]mintlify-development[bot]
authored
Documentation edits made through Mintlify web editor
1 parent 9f9e9aa commit e0099b1

File tree

5 files changed

+563
-952
lines changed

5 files changed

+563
-952
lines changed

‎api-playground/mdx/configuration.mdx‎

Lines changed: 143 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,161 @@ title: 'MDX Setup'
33
description: 'Generate docs pages for your API endpoints using MDX'
44
---
55

6-
Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
6+
## Overview
77

8-
<Steps>
9-
<Step title="Configure your API">
10-
In your `mint.json` file, define your base URL and auth method:
8+
Mintlify allows you to define your API endpoints using three key components:
119

12-
```json
13-
{
14-
"api": {
15-
"baseUrl": "https://mintlify.com/api", // string array for multiple base URLs
16-
"auth": {
17-
"method": "bearer" // options: bearer, basic, key.
18-
}
19-
}
10+
- Configuration in your `mint.json` file
11+
- MDX metadata fields for each endpoint
12+
- The `<ParamFields />` component for parameter documentation
13+
14+
From these definitions, we automatically generate:
15+
16+
- An interactive API playground
17+
- Request examples
18+
- Response examples
19+
20+
## Base Configuration
21+
22+
### API Base URL
23+
24+
First, define your API's base URL in the `mint.json` file. You can specify a single URL or an array for multiple base URLs:
25+
26+
```json
27+
{
28+
"api": {
29+
"baseUrl": "https://mintlify.com/api"
30+
}
31+
}
32+
```
33+
34+
For multiple base URLs:
35+
36+
```json
37+
{
38+
"api": {
39+
"baseUrl": [
40+
"https://api1.mintlify.com",
41+
"https://api2.mintlify.com"
42+
]
43+
}
44+
}
45+
```
46+
47+
### Authentication Method
48+
49+
Next, specify your API's authentication method in the same `api` section:
50+
51+
```json
52+
{
53+
"api": {
54+
"auth": {
55+
"method": "bearer" // options: bearer, basic, key
2056
}
21-
```
57+
}
58+
}
59+
```
2260

23-
If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
61+
### Playground Settings
2462

25-
```json
26-
{
27-
"api": {
28-
"playground": {
29-
"mode": "hide"
30-
}
31-
}
63+
By default, Mintlify shows an interactive API playground. You can hide this feature by adding:
64+
65+
```json
66+
{
67+
"api": {
68+
"playground": {
69+
"mode": "hide"
3270
}
33-
```
71+
}
72+
}
73+
```
74+
75+
<Info>
76+
Find a complete list of API configurations in our [Global Settings](/settings/global#api-configurations) documentation.
77+
</Info>
78+
79+
## Creating Endpoint Pages
80+
81+
### Basic Structure
3482

35-
Find a full list of API configurations [here](/settings/global#api-configurations).
36-
</Step>
37-
38-
<Step title="Create your endpoint pages">
83+
Each API endpoint needs its own MDX file. Start with this basic metadata structure:
3984

40-
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
85+
```md
86+
---
87+
title: 'Create new user'
88+
api: 'POST https://api.mintlify.com/user'
89+
---
90+
```
91+
92+
### Path Parameters
93+
94+
For endpoints with path parameters, wrap the parameter name with curly braces `{}`:
95+
96+
```bash
97+
https://api.example.com/v1/endpoint/{userId}
98+
```
4199

42-
```md
43-
---
44-
title: 'Create new user'
45-
api: 'POST https://api.mintlify.com/user'
46-
---
47-
```
100+
### Using Base URL
101+
102+
When you have configured `baseUrl` in your `mint.json`, you can use relative paths in your endpoint definitions:
103+
104+
```md
105+
---
106+
title: 'Get User Profile'
107+
api: 'GET /v1/users/{userId}'
108+
---
109+
```
48110

49-
You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
111+
<Note>
112+
The relative path will automatically be combined with your configured base URL.
113+
</Note>
50114

51-
```bash
52-
https://api.example.com/v1/endpoint/{userId}
53-
```
115+
## Navigation Setup
54116

55-
<Note>
117+
### Adding to Sidebar
56118

57-
If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
119+
Add your endpoint pages to the sidebar by including their paths in your `mint.json` navigation:
58120

59-
</Note>
60-
</Step>
121+
```json
122+
{
123+
"navigation": [
124+
{
125+
"group": "API Reference",
126+
"pages": [
127+
"api/create-user",
128+
"api/get-user",
129+
"api/update-user"
130+
]
131+
}
132+
]
133+
}
134+
```
135+
136+
### Organizing Endpoints
137+
138+
For better organization, group related endpoints together in your navigation structure:
139+
140+
```json
141+
{
142+
"navigation": [
143+
{
144+
"group": "User Management",
145+
"pages": [
146+
"api/users/create",
147+
"api/users/get",
148+
"api/users/update"
149+
]
150+
},
151+
{
152+
"group": "Authentication",
153+
"pages": [
154+
"api/auth/login",
155+
"api/auth/logout",
156+
"api/auth/refresh"
157+
]
158+
}
159+
]
160+
}
161+
```
61162

62-
<Step title="Add your endpoints to your docs">
63-
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
64-
</Step>
65-
</Steps>
163+
Learn more about structuring your docs in our [Navigation](/settings/navigation) guide.

0 commit comments

Comments
 (0)