Overview

Docs Kit's OpenAPI integration includes interactive features that let users test API endpoints directly from the documentation without leaving the browser.

Try It Button

Every API endpoint page includes a "Try It" button that opens an interactive modal for testing the endpoint.

Features

• Live API Testing - Execute real API requests
• Form-Based Input - User-friendly form fields for all parameters
• Raw JSON Mode - Toggle to raw JSON for complex requests
• Authentication - Support for various auth methods
• Response Display - Formatted response with syntax highlighting
• Request Preview - See the exact request being sent
• Code Generation - Get code examples in multiple languages

Request Building

Parameter Input

The Try It modal automatically generates input fields for all parameters:

Path Parameters

GET /api/users/{id}

Input field: id (marked as required if specified in spec)

Query Parameters

GET /api/users?role=admin&limit=10

Input fields for each query parameter with:

• Type validation (string, number, boolean)
• Enum dropdowns for predefined values
• Default values pre-filled

Header Parameters

X-Custom-Header: value
Accept-Language: en-US

Input fields for custom headers required by the endpoint.

Request Body Input

For POST/PUT/PATCH endpoints, choose between two input modes:

Form Mode

Schema-based form with fields for each property:

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "subscribed": true
}

Generates form fields:

• Text input for name (string)
• Email input for email (string with email format)
• Number input for age (number)
• Toggle switch for subscribed (boolean)

Raw JSON Mode

Direct JSON editing for complex structures:

{
  "name": "John Doe",
  "email": "john@example.com",
  "metadata": {
    "source": "web",
    "campaign": "spring-2024"
  },
  "tags": ["vip", "newsletter"]
}

Toggle between modes with the "Form" / "Raw JSON" tabs.

Authentication

The Try It modal automatically detects authentication requirements from your OpenAPI spec and provides appropriate input fields.

Supported Auth Types

X-API-Key: your_api_key_here

?api_key=your_api_key_here

Cookie: api_key=your_api_key_here

Authorization: Bearer eyJhbGc...

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Authentication values are stored in browser localStorage and persist across page reloads.

Response Display

Successful Response

When the request succeeds:

Status: 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Displayed with:

• Status code badge (green for 2xx)
• Syntax-highlighted JSON
• Collapsible sections for large responses
• Copy button for response body

Error Response

When the request fails:

Status: 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "invalid_request",
    "message": "Email is required"
  }
}

Displayed with:

• Status code badge (red for 4xx/5xx)
• Error message highlighted
• Helpful troubleshooting hints

Request Preview

See the exact request being sent:

cURL:

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com"
}

Request Headers:

Authorization: Bearer TOKEN
Content-Type: application/json
User-Agent: DocsKit/1.0

Code Generation

Generate code examples in multiple languages based on the current request:

const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.example.com/users',
    headers={
        'Authorization': 'Bearer TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'John Doe',
        'email': 'john@example.com'
    }
)

data = response.json()

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type": application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}'

$response = Http::withToken('TOKEN')
    ->post('https://api.example.com/users', [
        'name' => 'John Doe',
        'email' => 'john@example.com'
    ]);

$data = $response->json();

Code snippets update dynamically as you modify parameters and request body.

Base URL Configuration

The Try It modal uses the base URL from your OpenAPI spec:

{
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Production"
    },
    {
      "url": "https://api.sandbox.example.com",
      "description": "Sandbox"
    }
  ]
}

If multiple servers are defined, users can select which environment to use.

CORS Considerations

For the Try It feature to work, your API must:

1. Allow CORS from documentation domain
2. Handle preflight requests (OPTIONS)
3. Return appropriate CORS headers:

Access-Control-Allow-Origin: https://docs.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH
Access-Control-Allow-Headers: Authorization, Content-Type

User Experience Features

Validation

• Real-time validation of required fields
• Type checking (string, number, boolean)
• Format validation (email, URL, date)
• Enum value validation

Auto-Fill

• Default values from OpenAPI spec
• Previously used authentication tokens
• Example values when available

Error Handling

• Clear error messages
• Network error detection
• Timeout handling
• Retry suggestions

Persistence

• Auth tokens saved in localStorage
• Form values preserved during session
• Recently used values suggested

Best Practices

Provide Example Values

In your OpenAPI spec, include examples:

{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "name": {
            "type": "string",
            "example": "John Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "john@example.com"
          }
        }
      }
    }
  }
}

Examples auto-populate the Try It modal for easier testing.

Configure Test Environment

Use a sandbox/test environment as the default server:

{
  "servers": [
    {
      "url": "https://api.sandbox.example.com",
      "description": "Sandbox (recommended for testing)"
    },
    {
      "url": "https://api.example.com",
      "description": "Production"
    }
  ]
}

Add Helpful Descriptions

{
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "description": "Number of results to return (1-100). Default: 10",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 10
      }
    }
  ]
}

Descriptions appear as helper text in the Try It modal.

Finally, learn how to configure Authentication for your API endpoints.