OpenAPI Spec to Mock Server in 60 Seconds

The 60-Second Version

Have an OpenAPI spec? You have a mock server.

# Install
pip install apighost-cli

# Run
apighost serve petstore.yaml

# That's it. Your mock is live at http://127.0.0.1:8080

Output:

 APIGhost v2.4.0 - loading spec...
 Spec: petstore.yaml
 API: Petstore v1.0.0
 Endpoints: 8

 Mock server running → http://127.0.0.1:8080
 Press Ctrl+C to stop

Every endpoint defined in your spec now returns realistic fake data. No route definitions. No response templates. No JavaScript runtime. APIGhost reads your OpenAPI schema, infers data types from property names and format strings, and generates responses using Faker.

# Hit any endpoint from your spec
curl http://127.0.0.1:8080/pets

# Response:
[
  {
    "id": 42831,
    "name": "Buddy",
    "tag": "dog",
    "status": "active"
  },
  {
    "id": 71902,
    "name": "Whiskers",
    "tag": "cat",
    "status": "pending"
  }
]

How the Fake Data Gets Realistic

Most mock servers return "string" for every text field and 0 for every number. APIGhost uses a two-tier strategy to generate data that actually looks like your production API.

Tier 1: Format-String Matching

If your OpenAPI schema includes a format field, APIGhost uses it directly:

OpenAPI format	Generated Value
email	jessica.thompson@example.com
uri	https://www.miller.biz/
uuid	a1b2c3d4-e5f6-7890-abcd-ef1234567890
date-time	2025-11-14T08:23:41Z
ipv4	192.168.1.105
phone	(555) 123-4567
password	x7#kQ9!mR2pL

Tier 2: Property-Name Hints

When there's no format field, APIGhost matches on the property name itself. This covers the most common API field names without requiring any annotations:

Property Name	Generated Value
name	Sarah Mitchell
email	sarah.mitchell@example.com
company	Thompson and Sons
city	Portland
created_at	2025-08-30T14:22:11Z
avatar	https://api.dicebear.com/7.x/avataaars/svg?seed=smitchell
image	https://picsum.photos/seed/42831/400/300
role	editor

For property names that don't match any hint, APIGhost falls back to the JSON Schema type (string → random word, integer → random int, boolean → true/false).

What Happens at the Root URL

Navigating to http://127.0.0.1:8080/ shows an auto-generated API home page listing every route from your spec with method, path, and summary. This is useful for:

• Quickly verifying which endpoints were parsed from the spec
• Sharing a clickable reference with frontend developers
• Debugging missing routes without reading the YAML

Spec Hot-Reload with --watch

When you're iterating on your OpenAPI spec (adding endpoints, changing schemas), you don't want to restart the server every time. Use --watch:

apighost serve petstore.yaml --watch

APIGhost watches the spec file for changes and auto-reloads. Add a new endpoint to your YAML, save, and it's immediately available on the mock server — no restart needed.

Scenario Switching: Test Error Paths Without Code Changes

Testing happy paths is easy. Testing what happens when the API returns a 404, 422, or 500 is harder — you usually need to modify your mock code or add conditional logic.

APIGhost scenarios let you switch response profiles with a single flag:

# Create a scenario for 404 responses
apighost scenario create not_found
apighost scenario edit not_found "GET /pets/{id}" --status 404 --body '{"error": "Pet not found"}'

# Run the mock with the scenario
apighost serve petstore.yaml --scenario not_found

# Now GET /pets/123 returns 404 instead of 200

Common scenario patterns:

• error_400 — validation errors for POST/PUT endpoints
• error_500 — server errors for resilience testing
• empty — empty arrays and null objects for loading state testing
• rate_limited — 429 responses for retry logic testing

Auto-Generate a Scenario from the Spec

Don't want to manually define every endpoint override? Use the generate command:

apighost generate petstore.yaml --name happy-path

This creates a scenario with realistic 200 responses for every endpoint in your spec — up to 10 endpoints by default. Edit the generated file to customize specific routes.

Simulated Latency: Test Loading States

Every frontend developer has been burned by code that works great on localhost but breaks when the real API takes 200ms–2s to respond. APIGhost lets you simulate latency:

# Add 500ms delay to every response
apighost serve petstore.yaml --latency 0.5

Use this to:

• Test loading spinners and skeleton screens
• Verify race conditions in concurrent requests
• Validate timeout handling in your HTTP client

Path Parameters Work Automatically

APIGhost extracts path parameters from your spec and matches them at runtime:

# Spec defines: GET /pets/{petId}
curl http://127.0.0.1:8080/pets/42

# Response uses the path param for realistic output:
{
  "id": 42,
  "name": "Rex",
  "tag": "dog",
  "status": "active"
}

No route-specific code needed. The {petId} parameter is parsed from the OpenAPI spec and extracted from the incoming URL automatically.

VCR Recording: Capture Real Responses, Replay in Tests

When you need mock data that exactly matches a real API's behavior, record it:

# Record real API interactions
apighost serve stripe.yaml --record --cassette-name stripe-create-payment

# Make real API calls through the mock proxy...
# (APIGhost forwards to the real API and records the responses)

# Later, replay the recorded cassette
apighost replay stripe-create-payment

VCR recording auto-strips Authorization and Cookie headers from stored interactions, so you won't accidentally commit secrets. The recorded cassettes are portable JSON files you can commit to your repo and replay in CI.

CI Integration: Mock in Your Test Pipeline

GitHub Actions

name: API Integration Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install APIGhost
        run: pip install apighost-cli

      - name: Start mock server
        run: |
          apighost serve tests/fixtures/api-spec.yaml --port 8080 &
          sleep 2
          echo "Mock server ready"

      - name: Run integration tests
        env:
          API_BASE_URL: http://127.0.0.1:8080
        run: pytest tests/integration/

      - name: Stop mock server
        if: always()
        run: kill $(lsof -t -i:8080) 2>/dev/null || true

With Scenarios for Error Testing

# In CI: run tests against both happy and error scenarios
- name: Test happy path
  run: |
    apighost serve api-spec.yaml --scenario happy-path --port 8080 &
    sleep 2
    pytest tests/integration/ -k "not error"

- name: Test error responses
  run: |
    kill $(lsof -t -i:8080) 2>/dev/null || true
    apighost serve api-spec.yaml --scenario error_500 --port 8080 &
    sleep 2
    pytest tests/integration/ -k "error"

APIGhost vs. Other Mock Tools

Feature	APIGhost	Prism	WireMock	MSW
OpenAPI spec input	Yes (3.0 + 3.1)	Yes	No (manual)	No (manual)
Zero-config startup	Yes	Yes	No	No
Realistic fake data	Yes (Faker + hints)	Minimal (examples)	No (static)	No (static)
VCR record/replay	Yes	No	Yes (via proxy)	No
Scenario switching	Yes	No	Yes (mappings)	Yes (handlers)
Spec hot-reload	Yes (--watch)	No	No	N/A (in-browser)
Latency simulation	Yes (--latency)	No	Yes (delay)	No
Language runtime	Python	Go	JVM	Node.js
Auth header stripping	Yes (VCR)	N/A	Manual	N/A

Install and Start Mocking

# pip
pip install apighost-cli

# Homebrew (macOS / Linux)
brew tap Coding-Dev-Tools/tap
brew install apighost

# Scoop (Windows)
scoop bucket add Coding-Dev-Tools https://github.com/Coding-Dev-Tools/scoop-bucket
scoop install apighost

# Start mocking
apighost serve your-api-spec.yaml

Have an OpenAPI spec but no server yet? Use the Petstore spec to try it now:

# Download the canonical Petstore spec
curl -sL https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml -o petstore.yaml

# Start the mock
apighost serve petstore.yaml

# Test it
curl http://127.0.0.1:8080/pets

Star APIGhost on GitHub

What's Next

APIGhost is one of 11 CLI tools in the DevForge suite. If you're building and testing APIs, also check out:

• API Contract Guardian — catch breaking API changes in CI before they reach consumers
• APIAuth — manage, rotate, and audit API keys from the terminal
• Envault — diff, sync, and rotate environment variables across environments

For advanced patterns (stateful CRUD mocks, multi-scenario test suites, VCR in CI), see our advanced mock patterns guide.