Building an Interactive API Playground with Dokly: A Step-by-Step Tutorial

The first thing a developer does when evaluating an API is try it.

Not read about it. Not watch a demo video. Not book a call with sales. They open the docs, find a curl example, change the values to something that makes sense for their use case, and paste it into their terminal. If it works, they're sold. If it doesn't, or if the path from "find the endpoint" to "first successful call" takes more than five minutes, they close the tab and evaluate the next tool on their list.

A good API playground collapses that path. Instead of copying curl into a terminal, filling in parameters, remembering to URL-encode, and parsing the response, the developer clicks "Try It," fills in a form, and sees the real response inline. Time from "I'm curious" to "this works" drops from five minutes to thirty seconds.

This tutorial walks through building an interactive API playground in Dokly—from importing your OpenAPI spec to customizing the playground to handling authentication. By the end, you'll have an API reference where every endpoint is live and testable.

What You'll Build#

A complete API reference section with:

• Auto-generated pages for every endpoint in your OpenAPI spec
• Interactive "Try It" functionality on every endpoint
• Proper authentication handling (API keys, OAuth, bearer tokens)
• Auto-generated code examples in multiple languages
• Response examples that update to show real responses after testing

Estimated time: 30 minutes if you have an OpenAPI spec already. 2 hours if you need to write one from scratch.

Prerequisites#

• A Dokly account (free tier works for this tutorial)
• An OpenAPI 3.0 or 3.1 specification for your API (openapi.json or openapi.yaml)
• Basic familiarity with MDX and Markdown

If you don't have an OpenAPI spec, we'll cover the basics below. If you have one but haven't kept it updated, now's a good time—the quality of your playground depends directly on the quality of your spec.

Step 1: Prepare Your OpenAPI Spec#

An OpenAPI specification is a single file that describes every endpoint of your API—the paths, the parameters, the responses, the auth methods. It's the source of truth that the playground will read from.

A minimal OpenAPI 3.1 spec looks like this:

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: An example API for this tutorial.
servers:
  - url: https://api.example.com/v1
    description: Production
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          description: Number of users to return.
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []

A few notes on writing specs that produce a great playground:

Include operationId on every endpoint. Dokly uses this to generate clean, predictable URLs for your endpoint pages. If you skip it, you'll get URLs derived from the path, which are harder to link to.

Write detailed descriptions. The description fields become the prose on your endpoint pages. Good descriptions are the difference between docs that feel like reference material and docs that feel like a stack overflow answer.

Include example values. For every parameter and response field, include example values. Dokly uses these to pre-fill the playground form, which means developers can click "Send" immediately without figuring out what to type.

Declare security properly. Define your auth methods in components.securitySchemes and reference them in the security block. This tells the playground how to handle auth—more on this in Step 4.

Step 2: Import the Spec into Dokly#

In your Dokly dashboard, navigate to the API section and click "Import OpenAPI."

You have three options:

1. Upload a file — drag in your openapi.json or openapi.yaml
2. Paste a URL — point Dokly at a hosted spec (e.g., https://api.example.com/openapi.json)
3. Paste YAML/JSON directly — for quick experiments

The URL option is the most powerful. If you provide a URL, Dokly will re-fetch your spec periodically and regenerate pages automatically. Your docs stay in sync with your API without anyone having to remember to re-import.

After importing, Dokly creates:

• An API reference section in your sidebar, organized by the tags in your spec
• One page per endpoint, with auto-generated content based on the spec
• A playground embedded on every endpoint page
• A "Schemas" section documenting your data models

At this point you have a working playground. Every endpoint is interactive. Visitors can test your API right from the docs.

But there's still polish to add.

Step 3: Customize the Generated Pages#

The pages Dokly auto-generates are good starting points, but every API has context that doesn't belong in a machine-readable spec. That context is what separates reference material from documentation that developers actually learn from.

For each endpoint, Dokly generates an MDX file you can edit. Navigate to an endpoint page and click "Edit." You'll see something like:

---
title: "List Users"
description: "Returns a paginated list of users."
openapi: "GET /users"
---
 
Returns a list of all users in your workspace, paginated by the `limit`
parameter. Results are ordered by creation date, with the most recent first.

The openapi: "GET /users" line is what connects this page to the spec. Everything below that line is prose you can edit freely.

Good additions to consider for each endpoint:

A practical "when to use this" section. The spec says what the endpoint does. Your prose should say when to use it.

## When to use this endpoint
 
Use `GET /users` when you need a full or filtered list—for building
admin dashboards, running reports, or syncing users to another system.
 
For fetching a single user by ID, use the more efficient `GET /users/{id}`
endpoint instead.

Examples for common use cases. The playground handles the simple "just hit the endpoint" case. Your prose should cover the interesting cases.

## Common patterns
 
### Filtering by role
 
To get only admin users, pass `role=admin` in the query string:
 
```bash
curl "https://api.example.com/v1/users?role=admin" \
  -H "Authorization: Bearer $TOKEN"
```
 
### Paginating through all users
 
The response includes a `next_cursor` when more results are available:
 
```javascript
let cursor = null;
const allUsers = [];
 
do {
  const url = cursor
    ? `/users?cursor=${cursor}&limit=100`
    : `/users?limit=100`;
  const response = await fetch(url, { headers });
  const data = await response.json();
  allUsers.push(...data.users);
  cursor = data.next_cursor;
} while (cursor);
```

Notes on gotchas. Every API has edge cases. Document them.

<Callout type="warning">
  Deleted users continue to appear in this endpoint for 30 days after
  deletion, with `deleted_at` set. To exclude them, pass `include_deleted=false`.
</Callout>

The auto-generated content handles the mechanics. Your additions handle the knowledge.

Step 4: Configure Authentication#

Authentication is where most API playgrounds break. Developers either can't figure out how to authenticate, or the playground works but stores their real API key in a way that feels sketchy.

Dokly handles auth with a session-based approach: keys are stored in the browser's session storage (not cookies, not your servers, not a database), scoped to the docs site, and wiped when the tab closes.

For the most common auth patterns:

Bearer tokens#

If your spec declares bearerAuth, the playground automatically shows a "Bearer Token" input at the top of the reference section. Developers paste their token once and it applies to every endpoint on the page.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []

API key in header#

For APIs that use custom headers:

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - apiKeyAuth: []

The playground renders an input for the header value.

OAuth 2.0#

For OAuth flows, Dokly supports the authorization code flow out of the box. In your spec:

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

The playground includes a "Connect" button that triggers the full OAuth flow, then uses the resulting access token for requests.

Test credentials for public playgrounds#

If your docs are public (most are) and you want visitors to try the API without signing up, provide test credentials for a sandbox environment.

In your endpoint page's front-matter, you can set default auth:

---
title: "List Users"
openapi: "GET /users"
playground:
  defaultAuth:
    bearerAuth: "test_token_abc123"
---

Now the playground works out of the box with sandbox access. Convert-ready developers can plug in their real credentials later.

Step 5: Code Example Generation#

Dokly auto-generates code examples in seven languages from your OpenAPI spec: cURL, JavaScript (fetch), Node.js, Python (requests), Go, Ruby, and PHP.

These update live as the developer changes parameters in the playground. If they type a value into the name field, the JavaScript example updates to include that value. This dual feedback loop—see the request, see the code that makes the request, see the response—is what makes playgrounds effective for learning.

You can customize which languages appear and their order in your dokly.config:

{
  "api": {
    "codeExamples": {
      "languages": ["javascript", "python", "curl", "go"],
      "default": "javascript"
    }
  }
}

If you have an official SDK, you can add custom examples that show SDK usage rather than raw HTTP. Use tabs to let users switch between the SDK and raw fetch approaches:

<Tabs defaultValue="sdk">
  <TabsList>
    <TabsTrigger value="sdk">SDK</TabsTrigger>
    <TabsTrigger value="fetch">Fetch</TabsTrigger>
  </TabsList>
  <TabsContent value="sdk">
    ```javascript
    import { ExampleClient } from '@example/sdk';
    const client = new ExampleClient(process.env.API_KEY);
    const users = await client.users.list({ limit: 20 });
    ```
  </TabsContent>
  <TabsContent value="fetch">
    ```javascript
    const response = await fetch('https://api.example.com/v1/users?limit=20', {
      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }
    });
    const users = await response.json();
    ```
  </TabsContent>
</Tabs>

Most developers will prefer the SDK example. Showing both gives them a choice.

Step 6: Organize the Reference Section#

By default, Dokly organizes endpoints by the tags you've assigned in your OpenAPI spec. If you didn't tag your endpoints, they'll all appear under a generic "API" section.

For a polished reference, tag every endpoint in your spec:

paths:
  /users:
    get:
      tags: [Users]
      summary: List users
  /users/{id}:
    get:
      tags: [Users]
      summary: Get a user
  /subscriptions:
    get:
      tags: [Subscriptions]
      summary: List subscriptions

Then add tag descriptions at the top level:

tags:
  - name: Users
    description: Create, read, update, and delete users.
  - name: Subscriptions
    description: Manage recurring billing and plan changes.

Dokly uses these for the section headers and descriptions in your sidebar.

You can also add custom pages into your reference—a "Getting Started" page, an "Authentication" guide, a "Rate Limits" page. These are regular MDX files that live alongside your auto-generated endpoint pages.

Step 7: Test the Full Flow#

Before publishing, walk through the playground as a first-time user would.

1. Land on your API reference
2. Try to authenticate with the provided test credentials
3. Make a simple GET request
4. Make a POST request with body parameters
5. Copy the code example and run it in your terminal

If anything feels awkward—the auth input is in a weird place, the code example doesn't match what actually works, a parameter has no example value—fix it before your users hit it.

The most common issues we see:

• Missing example values — developers see empty input fields and don't know what to type
• Out-of-sync auth examples — the docs say "Bearer" but the spec says "X-API-Key"
• Playground works, code example doesn't — usually a mismatch between your spec's server URL and your actual API URL

A 10-minute walkthrough catches almost all of these.

Comparison: Mintlify's Approach#

Since Dokly is often compared to Mintlify, a few notes on how the playgrounds differ.

Mintlify's API playground is excellent and was the category leader for years. The capabilities are broadly similar—OpenAPI import, auto-generated endpoint pages, interactive "Try It," multi-language code examples.

The differences are mostly around pricing and ergonomics:

Pricing: Mintlify's API playground is included in their Pro plan ($300/month) and higher. Dokly includes it at $49/month and on the free tier for public API sites.

Auth handling: Mintlify stores auth tokens in their platform. Dokly stores them client-side only. For most teams this doesn't matter; for security-conscious teams, client-side-only is a meaningful difference.

Customization depth: Mintlify's playground is more polished out of the box. Dokly's is easier to customize at the code level. If you want to write a custom component that wraps the playground for a bespoke experience, Dokly makes that easier.

Spec update frequency: Both platforms support polling an OpenAPI URL for updates. Mintlify polls every 24 hours. Dokly polls every hour on Pro and Team plans.

The honest answer: if you're already on Mintlify and happy, the playground isn't a reason to switch. If you're evaluating platforms, Dokly's playground is comparable and 5–6x cheaper.

The Takeaway#

An interactive API playground used to be a premium feature reserved for enterprise docs platforms. That hasn't been true for a while, but many teams are still paying enterprise prices for it out of habit.

With Dokly, you can stand up a full API reference—auto-generated pages, interactive playground, multi-language code examples—in an afternoon, on a free plan, from any OpenAPI spec.

The result is what every API should have: a reference where developers go from curious to confident in a few clicks, instead of giving up and evaluating your competitor.

Ready to build yours? Start with Dokly and import your OpenAPI spec. If you don't have one, our docs include templates and generators to get you started.

Your next integration partner is about to open your docs. Make sure the first thing they do is click "Try It" and see a 200.