Skip to content

Add documentation for API playground prefill feature #1461

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

Merged
merged 5 commits into from
Oct 6, 2025
Merged

Add documentation for API playground prefill feature #1461

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2af7ce1
Update organize/settings.mdx
mintlify[bot] Oct 6, 2025
77f4ad0
Update api-playground/overview.mdx
mintlify[bot] Oct 6, 2025
4ecfee5
Update api-playground/overview.mdx
mintlify[bot] Oct 6, 2025
4800bef
Apply suggestions from code review
ethanpalm Oct 6, 2025
a917822
Update api-playground/overview.mdx
ethanpalm Oct 6, 2025
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
8 changes: 6 additions & 2 deletions api-playground/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

The playground is automatically generated from your OpenAPI specification or AsyncAPI schema so any updates to your API are automatically reflected in the playground. You can also manually create API reference pages after defining a base URL and authentication method in your `docs.json`.

We recommend generating your API playground from an OpenAPI specification. See [OpenAPI Setup](/api-playground/openapi-setup) for more information on creating your OpenAPI document.

Check warning on line 17 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L17 

Try to avoid using first-person plural like 'We'.

## Getting started

Expand Down Expand Up @@ -78,7 +78,7 @@
<Expandable title="playground" defaultOpen="True">
<ResponseField name="display" type="&quot;interactive&quot; | &quot;simple&quot; | &quot;none&quot;">
The display mode of the API playground.
- `"interactive"`: Display the interactive playground.

Check warning on line 81 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L81 

': D' should be in lowercase.
- `"simple"`: Display a copyable endpoint with no playground.
- `"none"`: Display nothing.

Expand All @@ -101,6 +101,9 @@
<ResponseField name="defaults" type="&quot;required&quot; | &quot;all&quot;">
Whether to show optional parameters in API examples. Defaults to `all`.
</ResponseField>
<ResponseField name="prefill" type="boolean">
Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
</ResponseField>
</Expandable>
</ResponseField>

Expand All @@ -114,13 +117,14 @@
},
"examples": {
"languages": ["curl", "python", "javascript"],
"defaults": "required"
"defaults": "required",
"prefill": true
}
}
}
```

This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets.
This example configures the API playground to be interactive with example code snippets for cURL, Python, and JavaScript. Only required parameters are shown in the code snippets, and the playground prefills request fields with example values.

Check warning on line 127 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L127 

In general, use active voice instead of passive voice ('are shown').

Check warning on line 127 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L127 

Did you really mean 'prefills'?

### Custom endpoint pages

Expand All @@ -132,9 +136,9 @@
- Add additional content like examples
- Control playground behavior per page

The `x-mint` extension is recommended so that all of your API documentation is automatically generated from your OpenAPI specification and maintained in one file.

Check warning on line 139 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L139 

In general, use active voice instead of passive voice ('is recommended').

Individual `MDX` pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.

Check warning on line 141 in api-playground/overview.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

api-playground/overview.mdx#L141 

In general, use active voice instead of passive voice ('are recommended').

For more information, see [x-mint extension](/api-playground/openapi-setup#x-mint-extension) and [MDX Setup](/api-playground/mdx/configuration).

Expand Down
3 changes: 3 additions & 0 deletions organize/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@
Font weight, such as 400, 700. Variable fonts support precise weights such as 550.
</ResponseField>
<ResponseField name="source" type="string (uri)">
URL to your font source, such as https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2. [Google Fonts](https://fonts.google.com) are loaded automatically when you specify a Google Font `family` name, so no source URL is needed.

Check warning on line 220 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L220 

In general, use active voice instead of passive voice ('are loaded').

Check warning on line 220 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L220 

In general, use active voice instead of passive voice ('is needed').
</ResponseField>
<ResponseField name="format" type="&quot;woff&quot; | &quot;woff2&quot;">
Font file format.
Expand Down Expand Up @@ -493,7 +493,7 @@

<Expandable title="Interaction">
<ResponseField name="drilldown" type="boolean">
Control automatic navigation behavior when selecting navigation groups. Set to `true` to force navigation to the first page when a navigation group is expanded. Set to `false` to prevent navigation and only expand or collapse the group. Leave unset to use the theme's default behavior.

Check warning on line 496 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L496 

In general, use active voice instead of passive voice ('is expanded').
</ResponseField>
</Expandable>
</ResponseField>
Expand Down Expand Up @@ -570,7 +570,7 @@
Destination path to redirect to. Example: `/new-page`
</ResponseField>
<ResponseField name="permanent" type="boolean">
Whether to use a permanent redirect (301). Defaults to `true`.

Check warning on line 573 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L573 

Use parentheses judiciously.
</ResponseField>
</Expandable>
</ResponseField>
Expand All @@ -581,13 +581,13 @@
<Expandable title="Contextual">
<ResponseField name="options" type="array of &quot;copy&quot; | &quot;view&quot; | &quot;chatgpt&quot; | &quot;claude&quot; | &quot;perplexity&quot; | &quot;mcp&quot; | &quot;cursor&quot; | &quot;vscode&quot;" required>
Actions available in the contextual menu. The first option appears as the default.
- `copy`: Copy the current page as Markdown to the clipboard.

Check warning on line 584 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L584 

': C' should be in lowercase.
- `view`: View the current page as Markdown in a new tab.

Check warning on line 585 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L585 

': V' should be in lowercase.
- `chatgpt`: Send the current page content to ChatGPT.

Check warning on line 586 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L586 

': S' should be in lowercase.
- `claude`: Send the current page content to Claude.
- `perplexity`: Send the current page content to Perplexity.
- `mcp`: Copies your MCP server URL to the clipboard.
- `cursor`: Installs your hosted MCP server in Cursor.

Check warning on line 590 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L590 

': I' should be in lowercase.
- `vscode`: Installs your hosted MCP server in VSCode.

<img src="/images/page-context-menu.png" alt="Contextual Menu" className="rounded-xl" />
Expand All @@ -600,7 +600,7 @@
</Expandable>
</ResponseField>

### API Configurations

Check warning on line 603 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L603 

'API Configurations' should use sentence-style capitalization.

<ResponseField name="api" type="object">
API documentation and interactive playground settings.
Expand Down Expand Up @@ -669,6 +669,9 @@
<ResponseField name="defaults" type="&quot;required&quot; | &quot;all&quot;">
Whether to show optional parameters in API examples. Defaults to `all`.
</ResponseField>
<ResponseField name="prefill" type="boolean">
Whether to prefill the API playground with data from schema examples. When enabled, the playground automatically populates request fields with example values from your OpenAPI specification. Defaults to `false`.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="mdx" type="object">
Expand Down Expand Up @@ -696,10 +699,10 @@
</Expandable>
</ResponseField>

### SEO and search

Check warning on line 702 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L702 

Spell out 'SEO', if it's unfamiliar to the audience.

Check warning on line 702 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L702 

'SEO and search' should use sentence-style capitalization.

<ResponseField name="seo" type="object">
SEO indexing configurations.

Check warning on line 705 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L705 

Spell out 'SEO', if it's unfamiliar to the audience.

<Expandable title="Seo">
<ResponseField name="metatags" type="object">
Expand Down Expand Up @@ -935,7 +938,7 @@
404 "Page not found" error handling.
<Expandable title="404">
<ResponseField name="redirect" type="boolean">
Whether to automatically redirect to the home page when a page is not

Check warning on line 941 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L941 

Use 'isn't' instead of 'is not'.
found.
</ResponseField>
<ResponseField name="title" type="string">
Expand Down Expand Up @@ -1491,7 +1494,7 @@

</CodeGroup>

If you already have the CLI installed, make sure it is up to date:

Check warning on line 1497 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L1497 

Use 'command-line tool' instead of 'CLI'.

Check warning on line 1497 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L1497 

Use 'it's' instead of 'it is'.

```bash
mint update
Expand All @@ -1505,7 +1508,7 @@
mint upgrade
```

This command will create a `docs.json` file from your existing `mint.json`. Review the generated file to ensure all settings are correct.

Check warning on line 1511 in organize/settings.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

organize/settings.mdx#L1511 

Avoid using 'will'.
</Step>
<Step title="Delete your mint.json file">
After verifying your `docs.json` is configured properly, you can safely delete your old `mint.json` file.
Expand Down
Loading