Release 1.42.0 — Caph: OpenAPI spec excellence

Summary

Cuts the 1.42.0 — Caph release. Lands the OpenAPI Spec Excellence work (PR #103) plus version-bump and docs updates.

The headline change is closing the trust gap between Glueful's generated openapi.json and runtime behavior — the spec is now rich enough that off-the-shelf
SDK generators (openapi-typescript, openapi-generator-cli, etc.) produce high-quality clients without manual editing. One documented breaking change to
the permission-exception envelope.

What's shipping

• Config-driven security schemes — new SecuritySchemeRegistry reads documentation.security_schemes + documentation.middleware_map; replaces 15
  hardcoded BearerAuth literals
• Unified ErrorResponse schema — {success, message, error: {code, error_code, timestamp, request_id}} with an error_code enum; all CRUD 4xx
  responses $ref it
• Deterministic operation IDs — OperationIdGenerator produces camelCase SDK method names; closes a hidden gap where comment-driven generation emitted
  operations without any operationId
• Pagination + field-selection components — PaginationMeta / PaginationLinks / per-resource envelope schemas match PaginatedResourceResponse;
  addRouteWithFieldsAttribute() helper surfaces ?fields= / ?expand= from #[Fields] attributes
• Auto-derived request examples — ExampleDeriver infers realistic JSON payloads from Validator rules and schema properties; @example annotation
  overrides
• OpenAPI 3.1 webhooks block — WebhookDocsBuilder emits the top-level webhooks object from documentation.webhooks config; documents the actual
  X-Glueful-Signature / X-Glueful-Timestamp headers WebhookDeliveryService sends
• generate:client CLI wrapper — thin command that shells out to openapi-typescript or openapi-generator-cli with safe defaults; Glueful does not
  own codegen logic

Breaking changes

• PermissionUnauthorizedException envelope unified to {success, message, error: {code, error_code, timestamp, request_id}} (was {success, message, code, error_code} at the top level). Consumers reading top-level code/error_code must read error.code/error.error_code instead. All other render paths
  already used the nested shape.

See CHANGELOG.md [1.42.0] for the full migration guide.

Verification

• composer test — 796 tests / 1684 assertions / 0 failures
• composer phpcs — clean
• composer analyse — no new PHPStan errors on any modified file (pre-existing baseline preserved)
• Cross-file consistency: Version.php / CHANGELOG.md / ROADMAP.md / docs site / api-skeleton all agree on 1.42.0 — Caph — 2026-05-20

Risk

Moderate. One documented breaking change with clear migration path. Other changes are additive (new OpenAPI components, new config keys, new CLI
command). No new env vars.