You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: 'Enable users to interact with your API'
3
+
description: 'Test and explore your API endpoints in real-time'
4
4
openapi: 'GET /plants/{id}'
5
5
hideApiMarker: true
6
6
icon: 'play'
7
7
---
8
8
9
-
The API playground is an interactive environment to make requests and preview an API endpoint.
9
+
## What is the API Playground?
10
10
11
-
<Info>
12
-
Autogenerating API pages with OpenAPI will automatically generate API
13
-
playground. Read more about using OpenAPI with Mintlify
14
-
[here](/api-playground/openapi).
15
-
</Info>
11
+
The API playground is an interactive environment that lets you test API endpoints directly in your documentation. Instead of copy-pasting code or using external tools, you can make API calls and see responses right on the page.
-**Real-time Testing**: Make API requests and see responses instantly
21
+
-**Authentication Support**: Securely test endpoints that require authentication
22
+
-**Parameter Editor**: Easily modify query parameters, headers, and request bodies
23
+
-**Response Viewer**: See formatted API responses with syntax highlighting
24
+
-**Code Snippets**: Get example code in multiple programming languages
25
+
26
+
## Getting Started
27
+
28
+
<Steps>
29
+
<Steptitle="Find an API endpoint">
30
+
Navigate to any API reference page in the documentation to see the interactive playground.
31
+
</Step>
32
+
33
+
<Steptitle="Configure parameters">
34
+
Fill in any required parameters, headers, or request body fields in the playground interface.
35
+
</Step>
36
+
37
+
<Steptitle="Send a request">
38
+
Click the "Send API Request" button to test the endpoint and see the response.
39
+
</Step>
40
+
41
+
<Steptitle="View results">
42
+
The response will appear below, showing the status code, headers, and formatted response body.
43
+
</Step>
44
+
</Steps>
45
+
46
+
<Note>
47
+
If you've configured your API documentation using OpenAPI (formerly Swagger), the API playground will be automatically generated for each endpoint. Learn more about using OpenAPI with Mintlify [here](/api-playground/openapi).
48
+
</Note>
49
+
50
+
## Example Playground
51
+
52
+
Here's an example of what the playground looks like in action:
<Accordiontitle="Do I need an API key to use the playground?">
71
+
If the API endpoint requires authentication, you'll need the appropriate credentials (like an API key) to make successful requests.
72
+
</Accordion>
73
+
74
+
<Accordiontitle="Can I save my test configurations?">
75
+
Currently, parameter values and configurations are not saved between sessions. We recommend keeping track of commonly used test values separately.
76
+
</Accordion>
77
+
78
+
<Accordiontitle="Are there any request limitations?">
79
+
The playground follows the same rate limits and restrictions as your API. Make sure to check your API's documentation for specific limitations.
80
+
</Accordion>
81
+
</AccordionGroup>
82
+
83
+
<Tip>
84
+
You can customize how the API playground appears in your documentation using global settings. See the [API playground configuration guide](/api-playground/configuration) for more details.
description: 'Preview changes locally to update your docs'
3
+
description: 'Learn how to preview and test your documentation changes locally'
4
4
---
5
5
6
-
<Info>
6
+
## Prerequisites
7
7
8
-
**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
8
+
Before you begin, make sure you have:
9
9
10
-
</Info>
10
+
1. Installed Node.js version 19 or higher
11
+
2. Access to a command line terminal
12
+
3. Your documentation files on your local machine
11
13
12
-
**Step 1**: Install Mintlify:
14
+
<Tip>
15
+
Not sure if you have Node.js installed? Open your terminal and run `node --version`. If you see a version number ≥ 19, you're good to go. If not, [download Node.js here](https://nodejs.org/).
16
+
</Tip>
13
17
14
-
<CodeGroup>
18
+
## Setting Up Local Development
19
+
20
+
### Step 1: Install Mintlify CLI
21
+
22
+
Choose one of these commands to install the Mintlify CLI (Command Line Interface) tool:
15
23
24
+
<CodeGroup>
16
25
```bash npm
17
26
npm i -g mintlify
18
27
```
@@ -24,16 +33,9 @@ description: 'Preview changes locally to update your docs'
24
33
```bash pnpm
25
34
pnpm add -g mintlify
26
35
```
27
-
28
36
</CodeGroup>
29
37
30
-
**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:
31
-
32
-
```bash
33
-
mintlify dev
34
-
```
35
-
36
-
Alternatively, if you do not want to install Mintlify globally you can use a run script available:
38
+
Don't want to install globally? You can run Mintlify directly:
37
39
38
40
<CodeGroup>
39
41
```bash npm
@@ -47,35 +49,44 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
47
49
```bash pnpm
48
50
pnpm dlx mintlify dev
49
51
```
50
-
51
52
</CodeGroup>
52
53
53
-
<Warning>
54
-
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
55
-
</Warning>
54
+
<Note>
55
+
If using Yarn, make sure you have version 2 or higher for the `dlx` command. [Learn more](https://yarnpkg.com/cli/dlx)
56
+
</Note>
56
57
57
-
A local preview of your documentation will be available at `http://localhost:3000`.
58
+
### Step 2: Start the Development Server
58
59
59
-
### Custom Ports
60
+
1. Open your terminal
61
+
2. Navigate to your documentation folder (where `mint.json` is located)
62
+
3. Run the following command:
60
63
61
-
By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command:
64
+
```bash
65
+
mintlify dev
66
+
```
67
+
68
+
Your documentation will now be available at `http://localhost:3000`. Any changes you make to your documentation files will automatically appear on this local preview.
69
+
70
+
## Customizing Your Setup
71
+
72
+
### Using a Different Port
73
+
74
+
By default, Mintlify runs on port 3000. To use a different port:
62
75
63
76
```bash
64
77
mintlify dev --port 3333
65
78
```
66
79
67
-
If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
68
-
69
-
```md
80
+
If your chosen port is already in use, Mintlify will automatically try the next available port:
81
+
```text
70
82
Port 3000 is already in use. Trying 3001 instead.
71
83
```
72
84
73
-
##Mintlify Versions
85
+
### Updating Mintlify
74
86
75
-
Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI:
87
+
Keep your Mintlify CLI up to date to ensure you have the latest features. Update using the same tool you used to install:
76
88
77
89
<CodeGroup>
78
-
79
90
```bash npm
80
91
npm i -g mintlify@latest
81
92
```
@@ -87,45 +98,62 @@ Please note that each CLI release is associated with a specific version of Mintl
87
98
```bash pnpm
88
99
pnpm up --global mintlify
89
100
```
90
-
91
101
</CodeGroup>
92
102
93
-
## Validating Links
103
+
## Development Tools
94
104
95
-
The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
105
+
### Check for Broken Links
106
+
107
+
Find and fix broken links in your documentation with this command:
96
108
97
109
```bash
98
110
mintlify broken-links
99
111
```
100
112
101
-
## Deployment
102
-
103
-
If the deployment is successful, you should see the following:
For the best development experience, we recommend:
113
116
114
-
We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
117
+
1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting
118
+
2. Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for consistent formatting
115
119
116
-
## Troubleshooting
120
+
## Common Issues and Solutions
117
121
118
122
<AccordionGroup>
119
-
<Accordiontitle='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
123
+
<Accordiontitle="Sharp Module Error on Mac (M1/M2)">
124
+
If you see an error about the "sharp" module on Mac:
125
+
1. Uninstall Mintlify: `npm remove -g mintlify`
126
+
2. Update to Node.js v19 or higher
127
+
3. Reinstall Mintlify: `npm install -g mintlify`
128
+
</Accordion>
120
129
121
-
This may be due to an outdated version of node. Try the following:
122
-
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
123
-
2. Upgrade to Node v19 or higher.
124
-
3. Reinstall mintlify: `npm install -g mintlify`
130
+
<Accordiontitle="Unknown Errors">
131
+
If you encounter unexpected issues:
132
+
1. Open your terminal
133
+
2. Navigate to your home directory: `cd ~`
134
+
3. Delete the Mintlify folder: `rm -rf .mintlify`
135
+
4. Try running `mintlify dev` again
125
136
</Accordion>
126
137
127
-
<Accordiontitle="Issue: Encountering an unknown error">
128
-
129
-
Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
138
+
<Accordiontitle="Changes Not Showing Up">
139
+
If your changes aren't appearing:
140
+
1. Check that your development server is running
141
+
2. Try refreshing your browser
142
+
3. Clear your browser cache
143
+
4. Restart the development server
130
144
</Accordion>
131
145
</AccordionGroup>
146
+
147
+
## Deployment Status
148
+
149
+
When your changes are successfully deployed, you'll see this confirmation:
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments