Auto-Generate API Demos from OpenAPI Specs

The Problem: Schema Duplication

You've carefully documented your API with OpenAPI. Every endpoint has request schemas, response schemas, field descriptions, and validation rules. Then you want to create a demo, and suddenly you're writing it all again:

# Traditional approach: manually define every form field
- rest: POST /users
  form:
    - name: email
      label: "Email Address"
      type: text
      required: true
    - name: name
      label: "Full Name"
      type: text
    - name: role
      label: "Role"
      type: select
      options:
        - value: user
          label: User
        - value: admin
          label: Admin
  results:
    - key: id
      label: "User ID"
      type: mono
    - key: email
      label: "Email"
    - key: createdAt
      label: "Created"
      type: relative_time

This is tedious, error-prone, and quickly falls out of sync with your actual API. When you add a field to your API, you have to remember to update the demo too.

The Solution: Point to Your OpenAPI Spec

DemoScript can read your OpenAPI specification and automatically generate form fields from request body schemas and result displays from response schemas. Here's how:

# Step 1: Add your OpenAPI spec URL to settings
settings:
  base_url: "https://api.example.com"
  openapi: "https://api.example.com/docs/openapi.json"

steps:
  # Step 2: Just specify the endpoint - forms are auto-generated!
  - rest: POST /users
    defaults:
      email: "demo@example.com"
      role: "admin"

That's it. DemoScript will:

1. Fetch your OpenAPI spec
2. Find the POST /users endpoint
3. Extract the request body schema
4. Generate form fields with correct types, labels, and validation
5. Apply your defaults: as pre-filled values

How Form Generation Works

Request Body to Form Fields

DemoScript maps OpenAPI schema types to appropriate form controls:

Field labels come from the description property in your schema, or are auto-generated from the property name (e.g., firstName becomes "First Name").

Response Schema to Result Display

When you omit the results: field, DemoScript can auto-generate result displays from the OpenAPI response schema. It uses intelligent type mapping based on field names and formats:

- rest: POST /users
  form:
    - name: email
      label: "Email"
      type: text
      required: true
    - name: name
      label: "Name"
      type: text
    - name: role
      type: select
      options: [...]
  results:
    - key: id
      label: "User ID"
      type: mono
    - key: createdAt
      type: relative_time
    # ... more fields

- rest: POST /users
  defaults:
    email: "demo@example.com"

Customization Options

Auto-generation doesn't mean loss of control. You can customize at multiple levels:

1. Pre-fill Values with defaults:

Set default values that appear in the auto-generated form:

- rest: POST /users
  defaults:
    email: "demo@example.com"
    role: "admin"
    company: "Acme Corp"

2. Override Specific Fields with form:

Need to customize a label or hide a field? Override just what you need:

- rest: POST /users
  defaults:
    email: "demo@example.com"
  form:
    - name: email
      label: "Work Email"  # Custom label
    - name: internal_id
      hidden: true         # Hide from form

The form: override uses smart merging — you only specify what you want to change. Type, required status, and options are inherited from OpenAPI.

3. Override Results Display

To show specific fields instead of auto-generated results:

- rest: POST /users
  results:
    - key: id
      label: "Your User ID"
      type: mono
    - key: email
      label: "Confirmed Email"

4. Per-Step OpenAPI Override

Calling an external API with a different spec? Override per-step:

- rest: POST /external-service/webhook
  openapi: "https://external-api.com/openapi.json"
  defaults:
    event: "user.created"

Supported Specifications

DemoScript supports both OpenAPI 3.0 and Swagger 2.0 specifications:

• OpenAPI 3.0: requestBody.content['application/json'].schema
• Swagger 2.0: parameters with in: body
• Schema references: $ref to #/components/schemas/ or #/definitions/
• Composition: allOf for schema inheritance

Real-World Example

Here's a complete demo using the Swagger Petstore API — notice how little configuration is needed:

title: "Petstore API Demo"
settings:
  base_url: "https://petstore.swagger.io/v2"
  openapi: "https://petstore.swagger.io/v2/swagger.json"

steps:
  - slide: |
      # Welcome to the Pet Store
      Let's explore the API with live requests.

  - rest: GET /pet/findByStatus?status=available
    title: "Find Available Pets"
    # Results auto-generated from response schema!

  - rest: POST /pet
    title: "Add a New Pet"
    defaults:
      name: "Fluffy"
      status: "available"
    # Form fields auto-generated from request schema!

  - rest: GET /store/inventory
    title: "Check Inventory"
    # Returns object - displayed as JSON tree

No manual form definitions. No result field mappings. The OpenAPI spec provides everything DemoScript needs.

Try It Yourself

The easiest way to see this in action is with DemoScript's built-in Sandbox API, which includes a complete OpenAPI spec:

settings:
  base_url: "/sandbox"
  openapi: "/sandbox/openapi.json"

steps:
  - rest: POST /auth/login
    defaults:
      email: "demo@example.com"
      password: "demo123"

  - rest: POST /users
    defaults:
      name: "New User"
      email: "user@example.com"

Run it locally with npx demoscript serve or check out the example gallery for live demos.

Summary

• Add openapi: to your settings to enable auto-generation
• Form fields are created from request body schemas
• Result displays are inferred from response schemas
• Use defaults: to pre-fill values
• Use form: or results: to override when needed
• Works with OpenAPI 3.0 and Swagger 2.0

This integration keeps your demos in sync with your API automatically. When your API changes, just update your OpenAPI spec — your demos update too.