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, 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!

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 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

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