Module openapi 

OpenAPI response validation (DW-070, #258).

This module validates upstream responses against the OpenAPI spec’s response schemas. When a response violates the spec, it is flagged as drift and optionally returned as a 502 to the client.

Design (section 5-API Mgmt, section 6-API Craft)

This is the runtime half of section 5-API Mgmt’s “OpenAPI-driven config” item, whose import/request-validation/mock half already shipped as DW-047 (M2). This is also the concrete implementation of Tier 3’s “Contract testing mode” (section 6-API Craft): verify live traffic conforms to the spec DW-047 imported, and flag drift.

Scope

This covers per-response schema-conformance drift, not route-set drift (whether the live route set has grown out of sync with the spec’s endpoint list).

Wildcard status codes (#258)

OpenAPI specs commonly use default, 2XX, 4XX, and 5XX as wildcard response keys. The validator resolves a concrete response status (e.g. 200) by trying, in order: exact match (200), family match (2XX), then default. The first match wins.

Content types (#258)

In addition to application/json, the validator extracts schemas for application/problem+json, application/vnd.api+json, text/plain, and application/xml. JSON-variant content types are parsed as JSON for schema validation; text/plain bodies are wrapped as JSON strings; application/xml schemas are registered (status-code validation) but body schema validation is skipped (JSON Schema cannot validate XML).

Strict mode (#258)

When strict is true, a response with no matching schema (unknown status or content type) returns Invalid instead of NoSchema. This enforces that every response must be covered by the spec.

Feature gate

The openapi_validation cargo feature must be enabled. Without it, the module is not compiled and config fields that reference OpenAPI response validation are accepted but inert.

Structs

ResponseKey

The key for a response schema: (path, method, status_pattern, content_type).

ResponseToValidate

A response to validate.

ResponseValidator

A compiled OpenAPI response validator.

ValidationError

A single validation error.

Enums

StatusPattern

A status pattern extracted from an OpenAPI response key.

ValidationResult

The result of validating a response.