English | 日本語

---

mockserv is a zero-dependency (runtime) CLI tool that spins up a local HTTP mock server from your OpenAPI 3.x or JSON Schema files using only Python's stdlib http.server.

No Node.js. No Docker. No manual stub writing. Just point it at your spec and start mocking.

Features

• OpenAPI 3.x & JSON Schema support -- Load .yaml, .yml, or .json specs
• Realistic mock responses -- Generated from example, type inference, and format hints
• Custom response overrides -- Override any endpoint with a simple YAML file
• Latency simulation -- Add artificial delays to simulate real-world network conditions
• Request logging -- Log to stdout or write structured JSON Lines for test assertions
• CORS enabled -- Ready for frontend development out of the box
• Zero runtime dependencies -- Only pyyaml is required; everything else is stdlib

Installation

pip install mockserv

Or install from source:

git clone https://github.com/izag8216/mockserv.git
cd mockserv
pip install -e .

Quick Start

1. Start from an OpenAPI spec

mockserv start petstore.yaml --port 8080

Your mock server is now running at http://localhost:8080.

2. Start from a JSON Schema

mockserv start user.json --port 8080

Auto-generated endpoints: GET /users, POST /users, GET /users/{id}, etc.

3. Add latency simulation

mockserv start api.yaml --delay 200

Every response will have a 200ms artificial delay.

4. Override responses

Create overrides.yaml:

"/pets:get:200":
  - id: 99
    name: Custom Pet
    tag: dog

Then run:

mockserv start petstore.yaml --responses overrides.yaml

5. Log requests

mockserv start api.yaml --log --log-file requests.jsonl

CLI Reference

mockserv start <spec> [options]
  --port PORT       Server port (default: 8080)
  --delay MS        Latency in milliseconds (default: 0)
  --responses FILE  YAML file with custom response overrides
  --log             Enable stdout request logging
  --log-file FILE   Write JSON Lines request log

mockserv validate <spec> [options]
  --strict          Validate schemas against meta-schema

How Mock Responses Are Generated

Priority order:

1. Custom override (--responses)
2. example field in schema
3. examples array (first item)
4. default field
5. Type inference:
   • string -> "string" (or format-aware: email, uri, uuid, date, etc.)
   • integer -> 0
   • number -> 0.0
   • boolean -> true
   • array -> [] (with items populated)
   • object -> {} (with required fields populated)

Project Structure

mockserv/
  src/mockserv/       # Core implementation
  tests/              # pytest suite
  examples/           # Sample specs
  docs/               # Detailed documentation

Contributing

See CONTRIBUTING.md.

License

MIT License (c) 2024 izag8216