OpenAPI examples end up serving two conflicting audiences: pretty, aspirational values for reference documentation and boring, deterministic values for mock servers and contract tests. OpenAPI Overlays (spec version 1.1.0) solve this by letting you layer separate example sets onto the same base spec without touching it. One overlay injects a deterministic happy-path fixture (fixed IDs, fixed timestamps) for mock servers like Prism to serve predictably; a second overlay injects edge-case fixtures — an empty list, a zero-price boundary, and a deterministic 429 with a problem+json body — for exercising error paths in tests. Documentation builds use the plain spec, test pipelines apply the overlays before spinning up mocks, so the ugly test data never leaks into public docs.
Questions this post answers
How do I keep my OpenAPI documentation examples separate from the fixed test data my mock server needs?
Use OpenAPI Overlays to inject deterministic example values onto specific response objects without modifying the base spec. One overlay can add a fixed-id, fixed-timestamp example for the happy path so contract tests can assert against stable values, while your documentation build still ships the original spec with its human-readable examples untouched. daily.dev surfaces practical OpenAPI patterns like this for teams refining their mock and contract-test setups.
How can I generate a deterministic 429 rate-limit response for testing without hitting a real API gateway?
Add an OpenAPI Overlay targeting the 429 response's application/problem+json content and define a fixed example with a type, title, status of 429, and a detail message like 'Rate limit exceeded. Retry after 60 seconds.' A mock server such as Prism then serves this canned response, letting tests exercise the throttled path without provoking a real rate limit. Developers wiring up rate-limit test coverage can track OpenAPI testing techniques like this on daily.dev.
What is the OpenAPI Overlay specification used for besides modifying documentation?
Overlay 1.1.0 is a specification for applying targeted changes to an existing OpenAPI document via JSONPath-style targets, and beyond documentation tweaks it can inject separate example sets for testing purposes, such as deterministic fixtures for mock servers or edge-case data like empty lists and zero-price boundaries, layered onto a spec without editing the original file. daily.dev helps API developers keep up with emerging OpenAPI tooling patterns like overlays.