oasmock

OASMock – OpenAPI Mock Server

A Go‑based mock server that leverages OpenAPI 3.0 schemas enhanced with custom extensions for conditional examples, state management, and runtime expressions.

Features

• Loads one or more OpenAPI 3.0 YAML/JSON files (with optional path prefixes)
• Supports custom extensions (x‑mock‑params‑match, x‑mock‑skip, x‑mock‑once, x‑mock‑set‑state, x‑mock‑headers)
• Runtime expressions ({$request.path.id}, {$state.counter}, {$env.VAR}) with modifiers (default, getByPath, toJWT)
• In‑memory state per namespace (get/set/increment/delete)
• Request history ring buffer with filtering via management API
• Dynamic example injection at runtime via HTTP API
• Configurable request delay, CORS, verbose logging
• Single binary, zero dependencies

Installation

From source

git clone https://github.com/mamonth/oasmock
cd oasmock
go install ./cmd/oasmock

Download binary

Pre‑built binaries for Linux, macOS and Windows are available on the Releases page.

Quick Start

1. Create an OpenAPI schema (api.yaml) with at least one endpoint:

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
paths:
  /hello:
    get:
      responses:
        200:
          description: OK
          content:
            application/json:
              examples:
                default:
                  value:
                    message: Hello, world!

1. Start the mock server:

oasmock --from api.yaml --port 8080 --verbose

1. Send a request:

curl http://localhost:8080/hello
# {"message":"Hello, world!"}

OpenAPI Extensions

OASMock adds several custom extensions to OpenAPI example objects. Full documentation is available in extensions.md.

x‑mock‑params‑match

Selects the example when the request matches the given conditions.

examples:
  admin:
    x‑mock‑params‑match:
      '{$request.header.role}': admin
    value:
      message: Welcome, admin!

x‑mock‑skip

Skips the example (useful for temporarily disabling an example).

x‑mock‑once

Makes the example one‑time only (removed after first match).

x‑mock‑set‑state

Updates server‑side state that can be referenced later via {$state.*}.

x‑mock‑set‑state:
  counter:
    increment: 1
  'user-{$request.path.id}':
    value: '{$request.body.name}'

x‑mock‑headers

Sets response headers (supports runtime expressions in values).

Runtime Expressions

Runtime expressions are enclosed in {$...} and can appear in extension keys, values, and response bodies.

Data Sources

• {$request.path.param}
• {$request.query.param}
• {$request.header.name}
• {$request.cookie.name}
• {$request.body.field}
• {$state.key}
• {$env.VARIABLE}

Modifiers

• {$request.query.id|default:unknown} – provides a default value if the expression cannot be resolved
• {$state.object|getByPath:deep.nested.value} – traverses an object
• {$state.payload|toJWT} – (stub) encodes the value as a JWT

Embedded expressions are supported:

value:
  url: "/api/users/{$request.path.id}/profile"

Management API

The server exposes a control HTTP API under the /_mock prefix.

GET /_mock/requests

Retrieves the request history (optionally filtered by path, method, time range, etc.).

POST /_mock/examples

Adds a dynamic example to an existing route. The request body follows the schema defined in openapi.yaml.

Command‑Line Interface

See cli.md for the complete CLI specification.

Examples

# Multiple schemas with prefixes
oasmock \
  --from api/v1/openapi.yaml --prefix /v1 \
  --from api/v2/openapi.yaml --prefix /v2 \
  --port 19191 --delay 500 --verbose

# Disable CORS and management API
oasmock --from api.yaml --nocors --no-control-api

# Environment variable overrides
export OASMOCK_PORT=9999
export OASMOCK_VERBOSE=true
oasmock --from api.yaml

Development

Building

go build ./cmd/oasmock

Testing

go test ./...

Linting

golangci-lint run

License

MIT