microcks-mocking

name	microcks-mocking
description	Microcks-compatible OpenAPI examples — rules for writing named examples that Microcks can pair as request/response mocks, including body-based dispatching and empty-body responses. Use when adding or modifying examples in an OpenAPI contract for Microcks mocking.
metadata	{"version":"1.0.0","microcks":"1.9.1"}

Microcks Mocking — OpenAPI Examples

Agent-oriented reference for writing OpenAPI examples that Microcks can consume as request/response mock pairs.

When to Use

• Adding or editing named examples (examples: blocks) in an OpenAPI contract
• Creating a new endpoint that needs to be mockable by Microcks
• Reviewing an OpenAPI spec for mocking correctness
• Debugging why a Microcks mock returns unexpected responses
• Adding error scenarios (400, 404, 500) to an existing operation

References

Topic	Description	Reference
Example Pairing	Name-matching rules between parameters, requestBody, and responses	example-pairing
JSON Body Dispatcher	POST body-based dispatching with x-mocking-microcks-dispatcher	json-body-dispatcher
Script Header Error Dispatcher	Header-based dispatching with x-mocking-microcks-dispatcher: script_header_error	script-header-error-dispatcher
Script Dispatcher	External Groovy script dispatcher for polymorphic bodies and multi-field routing	script-inline-dispatcher
Mock Server Integration	How start-mock-server.sh imports the spec and pushes dispatchers	mock-server-integration

Key Rules

1. Name matching: example names in parameters, requestBody, and responses MUST be identical so Microcks can pair them (e.g. success, not_found, server_error).
2. Empty-body responses: responses without a body (204, 200 with no content) MUST still have a content block with a named example (value: null) or Microcks will ignore the operation.
3. Error completeness: every error response example name MUST appear in ALL input locations (parameters and requestBody) that have named examples. Missing input examples cause Microcks to skip the error entirely.
4. POST dispatching: POST operations on collection endpoints (no path/query params) MUST use x-mocking-microcks-dispatcher: json_body at the operation level, with at least one request body field differing across examples.
5. PUT/PATCH/DELETE are excluded from body dispatching — they use URI-based dispatching via path parameters natively.
6. Header-based dispatching: operations without a discriminating parameter or body field (e.g. GET without query params, DELETE without unique path) can use x-mocking-microcks-dispatcher: script_header_error to dispatch on the error HTTP header (400 → invalid_input, 500 → server_error, default → success).
7. Polymorphic body dispatching: operations with polymorphic bodies (oneOf + discriminator) that need multi-field routing SHOULD use x-mocking-microcks-dispatcher: script with an inline Groovy script in x-mocking-microcks-dispatcher-rules. This is the most flexible dispatcher for complex routing logic.