Turn the diff into a work list
Create columns for route, method, declared auth, live auth, request fields, response fields, owner, and decision. A route absent from OpenAPI may be internal, forgotten, or intentionally hidden; test before deciding. For every field added to a live response, check whether it contains personal data. Run the comparison in CI so a new route or field triggers review before customers can reach it.
Test cases and proof
| Case | Expected result | Proof to keep |
|---|---|---|
| Live route absent from spec | Add to inventory or remove | Route diff |
| Spec marks auth but route accepts no token | Block route | Unauthorized response |
| Response has undocumented personal field | Remove or document with access rule | Raw body |
Synthetic example
The OpenAPI file lists GET /accounts but the live gateway also accepts PATCH /accounts/{id}. Put both in one route table. If PATCH is undocumented, inspect its authorization and either document or close it before release.
Evidence to keep
Preserve the OpenAPI revision and route inventory from the same deployment. Otherwise a difference may be caused by comparing different releases. Mark each gap as an undocumented route, missing auth declaration, changed request field, or extra response field. Give the gap an owner and a retest request. A spec-only edit does not close a live access flaw.
Do not rely only on source code routes. A proxy can rewrite paths and expose aliases that code search misses. Send safe requests to the deployed staging host and compare observed methods with the gateway export. Keep authentication tests within your authorized scope, using test identities for each role.
A spec difference needs a decision
An extra live route may be an approved internal operation, a forgotten old version, or an accidental public path. Do not delete it from a diff alone. First record whether the gateway exposes it and which identity can call it. A new response field may be harmless or may contain personal data. Give the route owner a decision: protect, document, or remove. Close the live flaw before treating a spec update as complete. Put the inventory comparison in CI so a future method change is reviewed before release.
Related reading
Why these checks matter
The OpenAPI specification defines a machine-readable API contract. OWASP API9 calls for an inventory of live endpoints, including their auth rules and versions. A comparison is useful only when both files describe the same deployment. Test a live mismatch before changing the spec, since documentation alone cannot close a route.
Read the security declaration exactly
Pin the OpenAPI version and revision for the deployment. A top-level security rule may be overridden on one operation. In OpenAPI 3.1.1, security: [] removes inherited security. An empty requirement object in the alternatives makes security optional. Two separate requirement objects are alternatives; two schemes within one object are required together. These details can change the intended test even when an auth scheme exists elsewhere in the file.
Synthetic route GET /accounts requires the customer token. PATCH /accounts/{id} is mistakenly declared with security: []. Test PATCH without a token at the live staging gateway. If runtime denies it, fix the spec mismatch; if runtime allows it, fix the route first. Do not assume generated clients or documentation enforce the declaration.
Make extra response fields visible
Adding riskScore to JSON does not always fail a schema test. A schema that permits additional properties can accept it. Use an explicit expected field set or a closed response schema for sensitive outputs, and test the actual serializer. Seed riskScore with a unique fake marker, then inspect the raw response under customer and staff roles.
Inventory gateway aliases, versioned routes, admin hosts, and methods from the running deployment. A list of successful traffic samples cannot show unused routes; a source list cannot show all gateway rewrites. Combine them and state missing coverage. Keep spec revision, deployed build, security requirement, observed response fields, and route-owner decision. OpenAPI 3.1.1 defines the contract rules; runtime checks prove enforcement.