Skip to main content

​
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. See Trigger an update for an example of the API playground in action.
API playground for the trigger an update endpoint.
The playground generates interactive pages for your endpoints based on your OpenAPI specification or AsyncAPI schema. If you modify your API, the playground automatically updates the relevant pages. We recommend generating your API playground from an OpenAPI specification. However, you can manually create API reference pages after defining a base URL and authentication method in your docs.json.

​
Get started

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. To generate other endpoint pages, add additional endpoints to the pages array.
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.
If the page has no groups property, all authenticated users see the interactive playground.
The auth display mode requires authentication to be configured for your documentation.

​
Custom endpoint pages

When you need more control over your API documentation, use the x-mint extension in your OpenAPI specification or create individual MDX pages for your endpoints. Both options allow you to:
  • Customize page metadata
  • 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. Individual MDX pages are recommended for small APIs or when you want to experiment with changes on a per-page basis.

​
Further reading

  • OpenAPI setup for more information on creating your OpenAPI document.
  • x-mint extension for more information on customizing your endpoint pages.
  • MDX setup for more information on manually creating individual API reference pages.
  • AsyncAPI setup for more information on creating your AsyncAPI schema to generate WebSocket reference pages.