openapi-driftlisted

# OpenAPI Drift ## Purpose Provide a standardized, static methodology for keeping an API specification and its implementation in sync, without starting the server. Two problems live here: **drift** (the spec and the code disagree about what the API does) and **breaking-change classification** (does a change to the surface break existing clients?). Both are read off the source: OpenAPI/Swagger YAML/JSON or GraphQL SDL on one side, and framework route/validation/serializer code on the other. This is the gap left when Optic (the popular OSS drift tool) was archived in January 2026. ## The two-model method 1. **Build the spec model**: endpoints (path + method), parameters, request/response schemas per status, required/nullable, security. From OpenAPI `paths`/`components`, or GraphQL `type`/`input`/`enum`/field args. 2. **Build the code model**: the same facts, read from the framework (routes, validators, DTOs, serializers, status calls). See `references/drift-signals.md`. 3. **Align** by path template + method (normalize `/x/{id}` ≡ `/x/:id`) or GraphQL type + field. 4. **Diff each axis** and record which side each fact came from, that provenance is what lets you assign authority. ## Drift classes and default authority | Drift class | Example | Usually authoritative | |---|---|---| | Undocumented endpoint | Route in code, absent from spec | Code (add to spec) | | Phantom endpoint | Endpoint in spec, no handler | Code (remove/implement), confirm intent | | Missing param | Hand