openapi-drift
This skill should be used when the user mentions "openapi", "swagger", "spec drift", "api contract", "breaking change", "oasdiff", "graphql schema", "api versioning", "the docs don't match the code",
SKILL.mdplugins/api-contract-keeper/skills/openapi-drift/SKILL.md
GitHubOpenAPI 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
- Build the spec model: endpoints (path + method), parameters, request/response schemas per status, required/nullable, security. From OpenAPI
paths/components, or GraphQLtype/input/enum/field args. - Build the code model: the same facts, read from the framework (routes, validators, DTOs, serializers, status calls). See
references/drift-signals.md. - Align by path template + method (normalize
/x/{id}≡/x/:id) or GraphQL type + field. - 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 | Handler reads ?status, spec omits it |
Code |
| Param type mismatch | Spec integer, code parses string |
Investigate; often code |
| Response field mismatch | Code returns a field the schema lacks | Depends, may be intentionally internal |
| Status-code mismatch | Code returns 409, spec lists only 200/400 |
Code |
| Nullability mismatch | Spec nullable: false, code can return null |
Code (bug) or spec (fix) |
| Auth mismatch | Spec security: [], code requires a token |
Code |
"Authoritative" is a default, not a law: a deliberate public contract can be the source of truth over an accidental code change. When ambiguous, surface it for a human rather than silently rewriting either side.
Breaking vs non-breaking, in one rule
Direction decides safety: request schemas are contravariant, widening is safe, narrowing breaks; response schemas are covariant, adding is safe, removing breaks. Adding a required request field, narrowing a type, removing a response field, changing a status code, or dropping/renaming anything are the breaking cases. The full matrix is in references/breaking-change-rules.md.
Semver mapping
- Any breaking change → major.
- Backward-compatible additions → minor.
- Description/example/docs-only → patch.
- Unclassifiable (dynamic schema, external
$refmoved,oneOfreshuffle) → default to breaking until a human confirms.
Additional Resources
Reference Files
references/drift-signals.md: per-framework: exactly where routes, params, request/response schemas, and status codes live in Express, Fastify, NestJS, Koa, FastAPI, Django REST Framework, Flask, Spring Boot, Go net/http/Gin, and Rails, plus GraphQL SDL vs resolvers, and how to read each into the code model.references/breaking-change-rules.md: the full breaking vs non-breaking classification for request bodies, response bodies, parameters, status codes, enums, and nullability, with oasdiff-style semantics and GraphQL-specific rules.