Changelog

For the canonical list, see CHANGELOG.md on GitHub and the npm release page.

v1.15 — Validation, completed

Closes the gap between what a route documents and what it enforces, and fixes the codegen type-safety holes that pushed consumers back to hand-written types. Across Express, Fastify, Hono, Koa, and NestJS:

Path-parameter schemas + validation — defineRoute({ request: { params } }) validates :id and friends with the same Zod schema that documents them, with a structured 422 on mismatch.
Request write-back — validate: { writeback: true } writes the parsed payload (Zod coercions + .default()s applied) back onto the request, so the handler reads coerced values instead of re-parsing them.
Dev-mode response assertion — validate: { response: 'warn' | 'throw' } checks a handler's response against the declared Zod response schema.
Status-keyed responses — response: { 201: schema, 200: schema } documents each status with its own schema.
defaultErrors config — declare shared error responses once; they merge into every route (the route's own errors win on a status conflict).
Standard DoctreenValidationError envelope — validated routes document their 422 body as a named component, so codegen emits the type.
defineSchema works with Zod — named schemas now emit $ref: '#/components/schemas/<name>' and codegen produces interface User instead of anonymous Schema1 / Schema2. Deep schemas no longer collapse to unknown.
Offline OpenAPI emit — getOpenApiDocument(app) on every adapter and the new doctreen emit-openapi CLI build a static openapi.json without a server.

v1.13 — Typed codegen

npx doctreen codegen types --from <url|file> emits a strict TypeScript declaration file: one export interface per components.schemas entry plus per-operation …Params / …Query / …Body / …Response shapes. npx doctreen codegen client --from <url|file> emits a self-contained zero-dependency typed fetch client — createClient({ baseUrl, fetch?, headers?, onRequest? }) with one async method per operation, errors as DoctreenHttpError. --watch [ms] for dev. Programmatic doctreen/codegen export.

See Typed codegen.

v1.12 — Mock server

npx doctreen mock --from <url|file> spins up an Express-backed fake of any OpenAPI 3.x document. CRUD short-circuits (with envelope detection) on /resource and /resource/:id, --latency, --error-rate, --persist flags, optional @faker-js/faker for realistic values, public doctreen/example and doctreen/mock exports.

See Mock server.

v1.11 — OpenAPI polish

$ref-based components.schemas dedup (named + auto-anonymous)
First-class per-route + top-level tags with descriptions and external docs
OpenAPI 3.1 callbacks (per-operation) and webhooks (document-level)
Multi-example bodies and responses, per-status response examples
npx doctreen lint openapi — Spectral-lite linter with CI-ready exit codes

See OpenAPI export.

v1.10.x — Schema drift, production grade

Structured pipeline with per-route aggregates and hourly buckets
Opt-in sampling (default 1 %)
onDrift callback + webhook dispatch
Pluggable DriftStore interface; Redis-backed reference implementation
Drift tab in the UI with per-route badges
npx doctreen drift report --fail-on-mismatch for CI
Opt-in POST <docsPath>/drift/reset (gated by drift.allowReset + optional resetToken)
Rolling 7-day dailyBuckets alongside the hourly 24h buckets

See Schema drift.

v1.9 — `headHtml` config

Inject analytics scripts, custom CSS, favicons, or OG metadata into the docs UI <head> without forking.

v1.8 — Security + hidden routes

openapi.servers + securitySchemes + per-route security
Authorization header auto-stripped when a security requirement is in effect
hidden: true per-route — keeps the runtime route reachable while removing it from docs / OpenAPI

v1.7 — OpenAPI 3.1 export

Same schema bag drives Scalar, Redoc, and Swagger UI via GET /docs/openapi.json.

v1.6 — Runtime validation

Zod schemas validate incoming requests; structured 422 on mismatch.

See Runtime validation.

On this page