Interactive Playground Setup

Overview

Configure interactive API testing environments that allow developers to make live API calls directly from your documentation. The playground automatically generates request forms from OpenAPI specifications and provides real-time response previews.

Use interactive playgrounds when you want to:

• Allow developers to test endpoints without external tools
• Provide immediate feedback on API responses
• Demonstrate authentication flows interactively
• Enable parameter experimentation within documentation
• Reduce friction in API adoption and testing

Basic Configuration

Enable Playground Features

Interactive playgrounds are automatically enabled when you include OpenAPI specifications in your documentation. The playground appears in the right sidebar alongside Request and Response components.

{
  "navigation": {
    "groups": [
      {
        "group": "API Reference",
        "openapi": "api/openapi.yaml",
        "pages": [
          {
            "title": "User Management",
            "path": "api/users"
          }
        ]
      }
    ]
  }
}

Playground Components

The interactive playground automatically generates:

• Parameter forms for path, query, and body parameters
• Authentication inputs based on security schemes
• Request preview showing the actual HTTP request
• Response viewer with syntax highlighting and formatting
• Status indicators for successful and failed requests

Authentication Configuration

API Key Authentication

For APIs using API key authentication, the playground provides secure input fields:

# In your OpenAPI specification
security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

The playground renders:

• Secure input field for the API key
• Header preview showing how the key will be sent
• Test button to validate authentication

Bearer Token Authentication

Configure Bearer token authentication for JWT-based APIs:

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Features include:

• Token input field with secure handling
• Automatic header injection (Authorization: Bearer <token>)
• Token validation indicators

OAuth 2.0 Integration

For OAuth 2.0 flows, the playground provides comprehensive authentication support:

security:
  - OAuth2: [read, write]

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.example.com/oauth/authorize
          tokenUrl: https://api.example.com/oauth/token
          scopes:
            read: Read access to resources
            write: Write access to resources

The playground includes:

• OAuth flow initiation with proper redirect handling
• Scope selection interface
• Token management with refresh capabilities
• Automatic token injection in requests

Request Customization

Parameter Forms

The playground automatically generates forms for all OpenAPI parameters:

Generated form includes:

• Path parameter input for id
• Query parameter checkbox for include
• Header management for authentication
• Validation based on OpenAPI schema constraints

Request Body Editing

For endpoints accepting request bodies, the playground provides:

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
              required: [name, email]

Features include:

• JSON editor with syntax highlighting
• Schema validation with real-time feedback
• Example generation from OpenAPI examples
• Format validation for email, date, etc.

Custom Headers

Add custom headers through the playground interface:

Response Handling

Live Response Display

The playground shows real-time responses with comprehensive formatting:

Response Analysis Features

• Status code highlighting with color-coded indicators
• Response time tracking for performance insights
• Header inspection showing all response headers
• Size metrics for response payload analysis
• Error categorization with troubleshooting hints

Advanced Features

Environment Management

Configure multiple environments for testing different API stages:

{
  "playground": {
    "environments": [
      {
        "name": "Production",
        "baseUrl": "https://api.example.com/v2",
        "description": "Live production API"
      },
      {
        "name": "Staging", 
        "baseUrl": "https://staging-api.example.com/v2",
        "description": "Pre-production testing environment"
      },
      {
        "name": "Development",
        "baseUrl": "http://localhost:3000/v2", 
        "description": "Local development server"
      }
    ]
  }
}

Request History

The playground maintains request history for developer convenience:

• Recent requests with quick replay functionality
• Saved requests for frequently used API calls
• Request bookmarking with custom names and descriptions
• History search to find previous API interactions

Code Generation

Generate ready-to-use code snippets from playground interactions:

const response = await fetch('https://api.example.com/v2/users/123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.example.com/v2/users/123',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    }
)

data = response.json()
print(data)

curl -X GET 'https://api.example.com/v2/users/123' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.example.com/v2/users/123", nil)
    req.Header.Add("Authorization", "Bearer YOUR_TOKEN")
    req.Header.Add("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Security and Privacy

Authentication Security

The playground implements secure authentication handling:

CORS Configuration

Ensure your API supports CORS for playground functionality:

// Example Express.js CORS configuration
app.use(cors({
  origin: ['https://your-docs.documentationai.app'],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key']
}));

Troubleshooting

Common Issues

Playground Not Appearing

If the interactive playground doesn't appear:

• Verify OpenAPI specification is properly referenced in documentation.json
• Check file paths to ensure OpenAPI files are accessible
• Validate OpenAPI format using tools like Swagger Editor
• Ensure endpoints have proper operationId values

Request Failures

For failed API requests in the playground:

• Check network connectivity to your API servers
• Verify authentication credentials and permissions
• Review CORS configuration on your API server
• Validate request parameters against OpenAPI schema requirements

Performance Optimization

Optimize playground performance for better user experience:

• Minimize OpenAPI file size by removing unused definitions
• Use response examples to provide immediate feedback
• Configure appropriate timeouts for long-running endpoints
• Implement request caching where appropriate