Playground

Enable users to interact with your API

Overview

The API playground is an interactive environment that lets users test and explore your API endpoints. Developers can craft API requests, submit them, and view responses without leaving your documentation.

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 for more information on creating your OpenAPI document.

Getting started

1. Add your OpenAPI specification file.

   Make sure that your OpenAPI specification file is valid using the Swagger Editor or Mint CLI.

   /your-project
     |- docs.json
     |- openapi.json
   

2. Configure `docs.json`.

   Update your docs.json to reference your OpenAPI specification. You can add an openapi property to any navigation element to auto-populate your docs with a page for each endpoint specified in your OpenAPI document.

   In this example, Mintlify will generate a page for each endpoint specified in openapi.json and organize them under the “API reference” group in your navigation.

   {
       "navigation": [
         {
           "group": "API reference",
           "openapi": "openapi.json"
         }
     ]
   }
   

Customizing your playground

You can customize your API playground by defining the following properties in your docs.json.

playground · object

Configurations for the API playground.

Hide playground

display · "interactive" | "simple" | "none"

The display mode of the API playground.

• "interactive": Display the interactive playground.
• "simple": Display a copyable endpoint with no playground.
• "none": Display nothing.

Defaults to interactive.

proxy · boolean

Whether to pass API requests through a proxy server. Defaults to true.

examples · object

Configurations for the autogenerated API examples.

Hide examples

languages · array of string

Example languages for the autogenerated API snippets.

Languages display in the order specified.

defaults · "required" | "all"

Whether to show optional parameters in API examples. Defaults to all.

Example configuration

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}

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.

Custom MDX pages

When you need more control over your API documentation, create individual MDX pages for your endpoints. This allows you to:

• Customize page metadata
• Add additional content like examples
• Hide specific operations
• Reorder pages in your navigation
• Control playground behavior per page

See MDX Setup for more information on creating individual pages for your API endpoints.

Further reading

• AsyncAPI Setup for more information on creating your AsyncAPI schema to generate WebSocket reference pages.