Changelog

DocTreen ships as three packages, each with its own release cadence. The canonical lists live with each package:

The version numbers are independent — a feature lands in Node first and is ported at the last shipped behavior (the Python and PHP packages skip the intermediate iterations), verified against the shared conformance fixtures.

Python — doctreen on PyPI

v0.0.x — Alpha: Flask end to end, FastAPI + Django, flows as pytest tests

The alpha line of the Python implementation, covering phases 0–5:

• Schema builder (s.*) mirroring the Node helper method-for-method
• Route registry + OpenAPI 3.1 exporter — output verified byte-for-byte against the Node reference by the shared conformance suite
• Pydantic v2 adapter — models document and validate
• Docs UI — the exact stylesheet + browser script the npm package builds, synced verbatim
• Flask adapter — blueprint mount, @define_route, path-parameter types from Flask URL converters
• Runtime validation — structured 422, write-back, status-aware response assertion (ported directly at the v1.16 behavior, not replayed version-by-version)
• Schema drift detection — same event kinds, same /drift.json format, pluggable stores with an announce_routes hook; lenient on query/path strings, exact on JSON bodies
• FastAPI adapter — reads app.openapi() rather than deriving; mounts the shared UI + drift at /doctreen, beside FastAPI's own docs
• Django / DRF adapter — URLconf introspection, DRF serializer schemas, ViewSet-action expansion, drift middleware
• Integration flows — the shared flow JSON, run as pytest tests (*.flow.json, plugin auto-registered on install) or via the doctreen-flow CLI

Not yet here: mock server and Python client codegen — see the roadmap.

PHP — doctreen/doctreen on Packagist

v0.1.0 — Early development: Laravel, phases 1–4

First tagged release of the PHP implementation, covering four phases in one:

• Core — S:: schema builder, route registry, ->doc() route macro, docs UI (shared assets), OpenAPI 3.1 export with $ref dedup, callbacks and webhooks (parity-tested against the npm exporter's output)
• Contract safety — 422 request validation with query & path-param coercion, status-aware response validation, config-level defaultErrors, schema drift detection with a cache-backed store
• Tooling — spec-driven mock server (doctreen mock), PHP codegen (doctreen codegen types|client — readonly DTOs + zero-dependency client), runnable flows (docs-UI runner + doctreen-flow CLI)
• Polish — lint openapi, emit-openapi, drift report|reset CLI

Next: Symfony and PSR-15 adapters — see the roadmap.

Node.js — doctreen on npm

v1.16 — Status-aware response validation

validate: { response } now asserts each response against the schema declared for its actual status code, so error envelopes (4xx/5xx) stop producing phantom success-schema warnings while genuine 2xx drift is still caught. This is the behavior the Python and PHP ports implement from day one.

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.