Skip to content

Improve Documentation Readability and Simplify Onboarding Experience #486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Improve Documentation Readability and Simplify Onboarding Experience #486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 77 additions & 7 deletions api-playground/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,85 @@
---
title: 'Interactive Playground'
description: 'Enable users to interact with your API'
description: 'Test and explore your API endpoints in real-time'
openapi: 'GET /plants/{id}'
hideApiMarker: true
icon: 'play'
---

The API playground is an interactive environment to make requests and preview an API endpoint.
## What is the API Playground?

<Info>
Autogenerating API pages with OpenAPI will automatically generate API
playground. Read more about using OpenAPI with Mintlify
[here](/api-playground/openapi).
</Info>
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.

<Frame>
<img className="block dark:hidden" src="/images/api-playground-light.png" alt="API Playground Example" />
<img className="hidden dark:block" src="/images/api-playground-dark.png" alt="API Playground Example" />
</Frame>

## Key Features

- **Real-time Testing**: Make API requests and see responses instantly
- **Authentication Support**: Securely test endpoints that require authentication
- **Parameter Editor**: Easily modify query parameters, headers, and request bodies
- **Response Viewer**: See formatted API responses with syntax highlighting
- **Code Snippets**: Get example code in multiple programming languages

## Getting Started

<Steps>
<Step title="Find an API endpoint">
Navigate to any API reference page in the documentation to see the interactive playground.
</Step>

<Step title="Configure parameters">
Fill in any required parameters, headers, or request body fields in the playground interface.
</Step>

<Step title="Send a request">
Click the "Send API Request" button to test the endpoint and see the response.
</Step>

<Step title="View results">
The response will appear below, showing the status code, headers, and formatted response body.
</Step>
</Steps>

<Note>
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).
</Note>

## Example Playground

Here's an example of what the playground looks like in action:

<Frame>
<img className="block dark:hidden" src="/images/api-playground-example-light.png" alt="API Playground Demo" />
<img className="hidden dark:block" src="/images/api-playground-example-dark.png" alt="API Playground Demo" />
</Frame>

The playground includes:
1. Method selector and endpoint URL
2. Authentication settings (if required)
3. Parameter inputs
4. Request body editor (for POST/PUT requests)
5. Response viewer
6. Code snippet generator

## Common Questions

<AccordionGroup>
<Accordion title="Do I need an API key to use the playground?">
If the API endpoint requires authentication, you'll need the appropriate credentials (like an API key) to make successful requests.
</Accordion>

<Accordion title="Can I save my test configurations?">
Currently, parameter values and configurations are not saved between sessions. We recommend keeping track of commonly used test values separately.
</Accordion>

<Accordion title="Are there any request limitations?">
The playground follows the same rate limits and restrictions as your API. Make sure to check your API's documentation for specific limitations.
</Accordion>
</AccordionGroup>

<Tip>
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.
</Tip>
130 changes: 79 additions & 51 deletions development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,27 @@
---
title: 'Local Development'
description: 'Preview changes locally to update your docs'
description: 'Learn how to preview and test your documentation changes locally'
---

<Info>
## Prerequisites

**Prerequisite**: Please install Node.js (version 19 or higher) before proceeding.
Before you begin, make sure you have:

</Info>
1. Installed Node.js version 19 or higher
2. Access to a command line terminal
3. Your documentation files on your local machine

**Step 1**: Install Mintlify:
<Tip>
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/).
</Tip>

<CodeGroup>
## Setting Up Local Development

### Step 1: Install Mintlify CLI

Choose one of these commands to install the Mintlify CLI (Command Line Interface) tool:

<CodeGroup>
```bash npm
npm i -g mintlify
```
Expand All @@ -24,16 +33,9 @@ description: 'Preview changes locally to update your docs'
```bash pnpm
pnpm add -g mintlify
```

</CodeGroup>

**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command:

```bash
mintlify dev
```

Alternatively, if you do not want to install Mintlify globally you can use a run script available:
Don't want to install globally? You can run Mintlify directly:

<CodeGroup>
```bash npm
Expand All @@ -47,35 +49,44 @@ Alternatively, if you do not want to install Mintlify globally you can use a run
```bash pnpm
pnpm dlx mintlify dev
```

</CodeGroup>

<Warning>
Yarn's "dlx" run script requires yarn version >2. See [here](https://yarnpkg.com/cli/dlx) for more information.
</Warning>
<Note>
If using Yarn, make sure you have version 2 or higher for the `dlx` command. [Learn more](https://yarnpkg.com/cli/dlx)
</Note>

A local preview of your documentation will be available at `http://localhost:3000`.
### Step 2: Start the Development Server

### Custom Ports
1. Open your terminal
2. Navigate to your documentation folder (where `mint.json` is located)
3. Run the following command:

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:
```bash
mintlify dev
```

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.

## Customizing Your Setup

### Using a Different Port

By default, Mintlify runs on port 3000. To use a different port:

```bash
mintlify dev --port 3333
```

If you attempt to run Mintlify on a port that's already in use, it will use the next available port:

```md
If your chosen port is already in use, Mintlify will automatically try the next available port:
```text
Port 3000 is already in use. Trying 3001 instead.
```

## Mintlify Versions
### Updating Mintlify

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:
Keep your Mintlify CLI up to date to ensure you have the latest features. Update using the same tool you used to install:

<CodeGroup>

```bash npm
npm i -g mintlify@latest
```
Expand All @@ -87,45 +98,62 @@ Please note that each CLI release is associated with a specific version of Mintl
```bash pnpm
pnpm up --global mintlify
```

</CodeGroup>

## Validating Links
## Development Tools

The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
### Check for Broken Links

Find and fix broken links in your documentation with this command:

```bash
mintlify broken-links
```

## Deployment

If the deployment is successful, you should see the following:

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
/>
</Frame>
### Code Editor Setup

## Code Formatting
For the best development experience, we recommend:

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.
1. Install the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for proper syntax highlighting
2. Use [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for consistent formatting

## Troubleshooting
## Common Issues and Solutions

<AccordionGroup>
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
<Accordion title="Sharp Module Error on Mac (M1/M2)">
If you see an error about the "sharp" module on Mac:
1. Uninstall Mintlify: `npm remove -g mintlify`
2. Update to Node.js v19 or higher
3. Reinstall Mintlify: `npm install -g mintlify`
</Accordion>

This may be due to an outdated version of node. Try the following:
1. Remove the currently-installed version of mintlify: `npm remove -g mintlify`
2. Upgrade to Node v19 or higher.
3. Reinstall mintlify: `npm install -g mintlify`
<Accordion title="Unknown Errors">
If you encounter unexpected issues:
1. Open your terminal
2. Navigate to your home directory: `cd ~`
3. Delete the Mintlify folder: `rm -rf .mintlify`
4. Try running `mintlify dev` again
</Accordion>

<Accordion title="Issue: Encountering an unknown error">

Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again.
<Accordion title="Changes Not Showing Up">
If your changes aren't appearing:
1. Check that your development server is running
2. Try refreshing your browser
3. Clear your browser cache
4. Restart the development server
</Accordion>
</AccordionGroup>

## Deployment Status

When your changes are successfully deployed, you'll see this confirmation:

<Frame>
<img
className="rounded-md"
src="https://mintlify.s3-us-west-1.amazonaws.com/mintlify/images/checks-passed.png"
alt="Successful deployment status showing green checkmarks"
/>
</Frame>

Need help? Join our [community](https://mintlify.com/community) or contact [support](mailto:[email protected]).
20 changes: 12 additions & 8 deletions mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,12 +65,16 @@
"icon": "pen-paintbrush",
"pages": [
"development",
"web-editor"
"web-editor",
"quickstart"
]
},
"settings/global",
"settings/navigation",
"migration"
"migration",
"development",
"settings/global",
"snippets/getting-started"
]
},
{
Expand Down Expand Up @@ -105,7 +109,8 @@
"api-playground/mdx/authentication"
]
},
"api-playground/troubleshooting"
"api-playground/troubleshooting",
"api-playground/overview"
]
},
{
Expand Down Expand Up @@ -192,11 +197,10 @@
{
"group": "Chat API",
"pages": [
"advanced/rest-api/chat/create-topic",
"advanced/rest-api/chat/generate-message"
]
}

"advanced/rest-api/chat/create-topic",
"advanced/rest-api/chat/generate-message"
]
}
]
}
]
Expand Down
Loading
Loading