feat(zod-openapi): optional response validation (strict flags, hooks)

[mikan3rd]

Approach

Opt-in response checks aligned with PR #184 (strictStatusCode / strictResponse), with maintainer direction in mind: validate JSON before a Response exists by temporarily wrapping c.json and c.status for the openapi route handler, instead of re-reading the body from a finished response.

Failure handling is configurable via defaultResponseHook and per-route responseHook (third openapi argument may be a request Hook or { hook?, responseHook? }). If neither hook returns a Response, a small JSON 500 body is sent.

Caveats / assumptions

• Validation applies only to c.json (and c.status when inferring status). c.text / c.html / c.body and return new Response(...) are unchanged.
• Wrapping runs for the OpenAPI handler after built-in validators. Route middleware that returns without next() bypasses strict checks; c.json only after the handler returns is also outside the wrapped window.
• If a response defines multiple JSON-compatible content entries, strictResponse uses the first (object key order).
• OpenAPI range keys must use spec spelling (1XX–5XX, uppercase X).
• Default body-validation errors include Zod issues; production apps should use hooks to redact or simplify payloads.
• With either strict flag on, the handler runs inside an async wrapper (minor; may affect stack traces).
• strictResponse is skipped when the matched response has no JSON Zod schema (e.g. 204 with no body schema).

See README Response validation and Scope and limitations for the full contract; openapi JSDoc summarizes the hooks object and points there.

[changeset-bot]

🦋 Changeset detected

Latest commit: ad3c514

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hono/zod-openapi	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codecov]

Codecov Report

❌ Patch coverage is 94.33962% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.76%. Comparing base (52f2d8c) to head (d4f1e54).

Files with missing lines	Patch %	Lines
packages/zod-openapi/src/index.ts	94.33%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1819      +/-   ##
==========================================
+ Coverage   91.71%   91.76%   +0.05%     
==========================================
  Files         113      113              
  Lines        3803     3900      +97     
  Branches      964      990      +26     
==========================================
+ Hits         3488     3579      +91     
- Misses        283      289       +6     
  Partials       32       32              

Flag	Coverage Δ
zod-openapi	93.82% <94.33%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.