Docs

Guides and references for the Mockzilla tools. Pick one.

mock server

Run mock APIs from OpenAPI specs and static files: portable and codegen mode, services, contexts, config, commands, replay and storage.

Generate Go models, HTTP servers, clients and MCP tools from OpenAPI 3.0, 3.1 and 3.2 specs.

Overview: Mockzilla is an open-source mock server for OpenAPI. Point it at a spec and get a validated mock API in seconds. Tested on 2,200+ real-world specs.
How it works: The path a request takes through Mockzilla: config overrides, latency, error injection, upstream proxy, caching, validation, response generation and replay.

Portable mode: Run a mock server straight from OpenAPI specs and static files: install, inputs, directory shapes, flags, per-service config and context, hot reload.
Docker Compose: Run Mockzilla as a container next to your app: mount a services tree, set the global app config, and add a health check.
Codegen mode: Generate typed Go code from OpenAPI specs for a compiled mock service with custom handlers, middleware and a single binary.
Templates: GitHub templates to start a portable or codegen Mockzilla project with CI already set up.

Services: How Mockzilla turns folders into services: the directory shapes, the spec, static and merge modes, and where static responses go.
Contexts: Control the values Mockzilla generates with contexts: static values, fake data, functions, pattern matching, value lists and per-request overrides.
Fake values: Every fake: alias a Mockzilla context can use, from addresses, people and companies to internet, payment, time and UUID values.
Factory: Generate mock requests and responses from Go code with the factory package, without running the HTTP server.

App config: Server-wide settings in app.yml: home URL and root-mounted services, history, replay, storage and environment variables.
Service config: Per-service settings in config.yml: latency, error injection, endpoint overrides, caching, replay, upstream proxy, response headers and contexts.
Codegen config: Configure Go code generation for a codegen-mode service with codegen.yml: the defaults, filtering operations, overlays and custom settings.

service: Generate a complete mock service from an OpenAPI spec or static files: setup files and Go code in one step, with flags and examples.
generate: Generate Go models, a server, a client or MCP tools from an OpenAPI spec, with the same flags and config as mockzilla-codegen.
lint: Find schemas in an OpenAPI spec that no value can satisfy, before you serve or deploy it. Rules, flags, exit codes and examples.
simplify: Make large OpenAPI specs such as Stripe's smaller: remove anyOf and oneOf unions and limit the optional properties per schema.

Replay: Record upstream API responses and replay them when later requests match chosen fields: activation, match fields, keys and upstream-only mode.
Storage: How Mockzilla stores data: one shared backend with an isolated view per service, choosing a backend, schema install and the request cache.
Middleware: Add custom Go middleware to compiled services for auth, logging, request changes and state, with request history and service storage.

Overview: mockzilla-codegen generates Go models, HTTP servers, clients and MCP tools from OpenAPI 3.0, 3.1 and 3.2 specs. Tested on 2,200+ real-world specs.
Getting started: Install mockzilla-codegen as a Go tool, generate code from an OpenAPI spec, add a config file, and check generated files in CI.
Configuration: Every key of codegen.yaml, the output files and their defaults, and the JSON schema that gives your editor completion.

Types: How OpenAPI schemas become Go types: named inline objects, oneOf and anyOf unions, allOf merging, pointers, nullable values and defaults.
Naming: How mockzilla-codegen turns spec names into Go names and resolves name clashes the same way on every run.
Validation: Generated Validate methods in plain Go: required fields, patterns, limits, multipleOf and uniqueItems, checked on requests and responses.
Error types: Turn the error responses of an OpenAPI spec into Go error types with models.error-mapping, on the server and on the client.
Extensions: The x-go-* extensions mockzilla-codegen reads: your own Go types and names, optional pointers, nullable fields, MCP settings and masking.

Server: Generate a Go HTTP server from OpenAPI: the service interface, request decoding, response data, errors, 14 routers and starter files.
Client: Generate a typed Go HTTP client from OpenAPI: one method per operation, request options, response envelopes, streams and error types.
MCP tools: Generate Model Context Protocol tools over the generated Go client, registered on the official Go SDK, so an AI assistant can call your API.
Observability: Add OpenTelemetry tracing and metrics to the generated Go server and client with operation middleware and your own HTTP client.

Templates: Change the generated Go code with templates: replace blocks of the built-in templates, and write extra files from templates of your own.
Adding a router: How a router framework is built in mockzilla-codegen, and the steps to add a new one: the Framework interface and the router template.

Which guide: Move a Go project to mockzilla-codegen from oapi-codegen, oapi-codegen-dd or ogen: what changes and how big each move is.
From oapi-codegen: Move from oapi-codegen to mockzilla-codegen step by step: config keys, server and client changes, and every flag and extension mapped.
From oapi-codegen-dd: Move from oapi-codegen-dd v3 to mockzilla-codegen step by step: config keys, server and client changes, and every option mapped.
From ogen: Move from ogen to mockzilla-codegen step by step: optional values, response data in place of sum types, and every flag and extension mapped.