OASMock – OpenAPI Mock Server

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

Features

• Loads one or more OpenAPI 3.0 YAML/JSON files (with optional path prefixes)
• Supports custom extensions (x‑mock‑match, x‑mock‑skip, x‑mock‑once, x‑mock‑set‑state, x‑mock‑headers; legacy x‑mock‑params‑match alias still supported)
• 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 static binary, no runtime dependencies
• JSON‑RPC 2.0 gateway via x‑rpc extension (batch requests, notifications)

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.

Docker

docker pull itmamonth/oasmock:latest

Run with a mounted .oasmock.yaml config and your OpenAPI schemas:

docker run -v $(pwd)/.oasmock.yaml:/app/.oasmock.yaml \
           -v $(pwd)/schemas:/schemas:ro \
           -p 8080:8080 \
           itmamonth/oasmock:latest

See docs/docker.md for configuration, Docker Compose, image tags, and multi‑platform usage.

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!

2. Start the mock server:

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

3. Send a request:

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

OpenAPI Extensions

OASMock adds several custom extensions to OpenAPI example objects. Full reference: extensions.md.

Match Conditions (x‑mock‑match)

Selects the example when the request matches the given conditions (deprecated alias: x‑mock‑params‑match).

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

Other Extensions

Extension	Purpose
x‑mock‑skip	Temporarily exclude an example
x‑mock‑once	One‑time example (removed after first match)
x‑mock‑set‑state	Update server‑side state (supports increment, value, null for delete)
x‑mock‑headers	Set response headers (runtime expressions in values)

JSON‑RPC Gateway (x‑rpc)

Route calls by body field instead of URL path. See json-rpc.md.

Runtime Expressions

Runtime expressions are enclosed in {$...} and resolved at request time. Data sources: {$request.path.param}, {$request.query.param}, {$request.header.name}, {$request.body.field}, {$request.cookie.name}, {$state.key}, {$env.VARIABLE}.

Modifiers: \|default:value (fallback), \|getByPath:path (traverse nested objects), \|toJWT (stub).

Expressions can appear in extension keys, values, and response bodies. Full reference: extensions.md.

Management API

The server exposes a control HTTP API under the /_mock prefix. Full schema: api/openapi.yaml.

• GET /_mock/requests — request history (filterable by path, method, time range, pagination)
• POST /_mock/examples — add a dynamic example to an existing route

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

Further Reading

• CLI reference — all flags, env vars, config file (.oasmock.yaml)
• Extensions & runtime expressions — full x‑mock‑* / x‑rpc reference
• JSON‑RPC 2.0 — protocol details, batch support, error codes
• Architecture — component diagrams, interfaces, data flows
• CI/CD — pipeline, quality gates, release process
• Project standards — tech stack, conventions, testing, coverage policy
• Specifications (BDD) — requirement scenarios

License

MIT