Skip to main content
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.
API playground for testing endpoints

​
How it works

The playground automatically generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. When you modify your API specification, the playground automatically updates the relevant pages. We recommend generating your API playground from an OpenAPI specification for the best developer experience. However, you can also manually create API reference pages after defining a base URL and authentication method in your docs.json.

​
Quick start

1

Add your OpenAPI specification file

Validate your OpenAPI specification file using the Swagger Editor or Mint CLI command mint openapi-check <filename>.
/your-project
  |- docs.json
  |- openapi.json
2

Generate endpoint pages

Update your docs.json to reference your OpenAPI specification.To automatically generate pages for all endpoints in your OpenAPI specification, add an openapi property to any navigation element.This example generates a page for each endpoint specified in openapi.json and organizes the pages in the “API reference” group.
Generate all endpoint pages
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
To generate pages for only specific endpoints, list the endpoints in the pages property of the navigation element.This example generates pages for only the GET /users and POST /users endpoints.
Generate specific endpoint pages
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Customize your playground

Customize your API playground by defining the following properties in your docs.json.
​
playground
object
Configurations for the API playground.
​
examples
object
Configurations for the autogenerated API examples.

​
Example configuration

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 the request body with example values. 
{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required",
     "prefill": true
   }
 }
}

​
Auth-based playground display

Use the auth display mode to show the interactive playground only to authenticated users. This is useful when you want to let users view your API documentation publicly while restricting playground access to logged-in users. When display is set to auth:
  • Authenticated users see the interactive playground.
  • Unauthenticated users see no playground (equivalent to none).
You can also combine auth with the groups property in page frontmatter to restrict playground access to specific user groups.
Page with group-restricted playground
---
title: "Create user"
openapi: POST /users
playground: auth
groups: ["admin", "developer"]
public: true
---
In this example:
  • The page is publicly visible (anyone can view the documentation).
  • Only authenticated users in the admin or developer groups see the interactive playground.
  • Users not in those groups see no playground.
The auth display mode requires authentication to be configured for your documentation.

​
Next steps

OpenAPI setup

Learn how to create and configure your OpenAPI specification for auto-generated API docs

MDX setup

Document API endpoints manually with MDX files for granular control

Build docs developers (and LLMs) love

Get started for freeTalk to us