security field before anything else: an empty array removes the global requirement entirely, while an array containing an empty object only makes it optional, and the two look almost identical in a diff. Validate every example against its own schema yourself — the specification holds examples to SHOULD, so a conforming validator is not obliged to reject one full of invented fields.A generated OpenAPI file arrives clean. The linter passes. The document parses, the dialect resolves, every $ref points somewhere real, and the rendered documentation looks like the API. It is also describing a DELETE /orders/{orderId} that does not exist, and it has quietly made the refund endpoint public.
Neither of those is a syntax error. Both survive every structural check that runs in CI, because structural validity and truthfulness about a service are unrelated properties. The document is checked against the specification; nothing checks it against the code.
\n\nStart here, before route reconciliation and before schemas, because this is the single highest-consequence thing a generated description gets wrong and the one least likely to be caught by reading.
\n\nA description usually declares a global requirement, and the specification is explicit about what an operation can do to it. Of the root security field: \"Individual operations can override this definition. The list can be incomplete, up to being empty or absent.\" Of the operation-level field: \"This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.\"
So an operation carrying security: [] is not inheriting the global requirement, and it is not tightening it. It is unauthenticated.
security:\n - oauth2: [orders.read]\n\npaths:\n /orders/{orderId}/refund:\n post:\n operationId: refundOrder\n # Removes the global requirement. This endpoint is public.\n security: []\n\n /orders/{orderId}/receipt:\n get:\n operationId: getOrderReceipt\n # Authentication is OPTIONAL: satisfied by oauth2, and also by nothing.\n security:\n - oauth2: [orders.read]\n - {}\n\n /orders/{orderId}:\n delete:\n operationId: deleteOrder\n # Genuinely tightened: a different scope is now required.\n security:\n - oauth2: [orders.admin]\nThe specification describes the middle case separately: \"To make security optional, an empty security requirement ({}) can be included in the array.\" Three operations, three different authorization postures, distinguished by two characters of YAML. In a pull-request diff they occupy the same amount of space and read as the same kind of change.
Models produce all three. A model asked to describe a public health endpoint learns security: [] as a shape, and will reuse that shape on an operation it has decided is \"read-only\" or \"internal\". It has no access to the authorization policy and no way to know that the refund endpoint is the one that moves money.
The review step is mechanical and worth automating, because reading for it does not work — the eye slides over [].
import { readFileSync } from \"node:fs\";\nimport { parse } from \"yaml\";\n\nconst doc = parse(readFileSync(\"openapi.yaml\", \"utf8\"));\nconst globalRequirement = doc.security ?? [];\nconst METHODS = [\"get\", \"put\", \"post\", \"delete\", \"options\", \"head\", \"patch\", \"trace\"];\n\nfor (const [path, item] of Object.entries(doc.paths ?? {})) {\n for (const method of METHODS) {\n const op = item[method];\n if (!op || !(\"security\" in op)) continue; // inherits the global requirement\n\n const declared = op.security;\n const posture =\n declared.length === 0\n ? \"UNAUTHENTICATED (global requirement removed)\"\n : declared.some((r) => Object.keys(r).length === 0)\n ? \"OPTIONAL (an empty requirement is present)\"\n : \"overridden\";\n\n console.log(`${method.toUpperCase()} ${path} -> ${posture}`);\n }\n}\n\nif (globalRequirement.length === 0) {\n console.log(\"NOTE: no global security; every operation is open by default.\");\n}\nFail the build on the first two postures unless the operation is on a written allowlist. The allowlist is the point: it forces someone to name each public endpoint deliberately, which is a different act from a model emitting two characters.
\n\nThe second question is whether the operations correspond to code. A generated description drifts in both directions at once, and the two drifts have different consequences.
\n\nAn invented operation is the visible failure. A consumer generates a client from it, calls the endpoint, and gets a 404 from a route that was never implemented. It is embarrassing but it surfaces immediately.
\n\nA missing operation is worse and quieter. An endpoint that exists and is absent from the description is outside every contract test, every mock server and every compatibility gate that reads the file. It is a live, unversioned, untested surface, and nothing in the pipeline reports it, because every tool downstream treats the description as the definition of the API.
\n\nSo take the inventory from the router at runtime rather than from a source scan, which misses dynamically mounted routes:
\n\n// Express 4: walk the router stack of the app you actually boot.\nfunction routeInventory(app) {\n const found = new Set();\n for (const layer of app._router.stack) {\n if (!layer.route) continue;\n // Express \":param\" -> OpenAPI \"{param}\"\n const path = layer.route.path.replace(/:([A-Za-z0-9_]+)/g, \"{$1}\");\n for (const [method, enabled] of Object.entries(layer.route.methods)) {\n if (enabled) found.add(`${method.toUpperCase()} ${path}`);\n }\n }\n return found;\n}\n\nconst described = new Set();\nfor (const [path, item] of Object.entries(doc.paths ?? {})) {\n for (const method of METHODS) {\n if (item[method]) described.add(`${method.toUpperCase()} ${path}`);\n }\n}\n\nconst implemented = routeInventory(app);\nconst invented = [...described].filter((r) => !implemented.has(r));\nconst undocumented = [...implemented].filter((r) => !described.has(r));\nReport both lists and fail on both. The reconciliation is also where parameter names get checked: matching GET /orders/{id} against GET /orders/{orderId} is a mismatch worth surfacing rather than normalising away, because a generated client will use the name from the description in its method signatures.
Two spellings of the same path are a specification error rather than a style question. Of path templating, the specification states that given /pets/{petId} and /pets/{name}, \"the following paths are considered identical and invalid\". It also warns that /{entity}/me alongside /books/{id} \"may lead to ambiguous resolution\", and that \"in case of ambiguous matching, it's up to the tooling to decide which one to use\" — meaning two generators can resolve the same document differently and both be conforming. A model producing a large paths object from separate prompts is exactly the process that emits both spellings.
While walking operations, check operationId too. It \"MUST be unique among all operations described in the API\", and \"the operationId value is case-sensitive\", so getOrder and getorder are two valid identifiers that will collide in most generated clients regardless.
This is the trap that survives a strict pipeline, and it is worth stating precisely because the usual folklore is wrong.
\n\nOf the mutually exclusive example and examples fields in the Parameter and Media Type Objects, the specification says they \"SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation\". SHOULD, not MUST. An example carrying a field the schema does not permit is not a specification violation, so a conforming validator may accept the document in full — and most do.
That matters because examples are the part of the description humans actually read. They are rendered at the top of the documentation, they become the fixture a frontend developer codes against, and they are frequently the seed for a mock server. An invented loyaltyTier in an example propagates into a client, a mock and a test before anyone consults the schema.
There are also four places an example can live, with different meanings, and a generated document scatters them:
\n\nexample and examples on the Parameter or Media Type Object, which are mutually exclusive and show the serialized form.examples on the Schema Object, which is the JSON Schema array and, in the specification's words, \"the preferred way to include examples in the Schema Object\".example on the Schema Object, \"retained purely for compatibility with older versions of the OpenAPI Specification\".The precedence is stated: because the Parameter and Media Type fields represent the final serialized form, \"they SHALL override any example in the corresponding Schema Object\". So a correct schema-level example and a wrong media-type example do not average out. The wrong one wins in the rendered docs.
\n\nValidate them yourself, against the schema in the same document:
\n\nimport Ajv2020 from \"ajv/dist/2020.js\";\n\nconst ajv = new Ajv2020({ strict: false, allErrors: true });\n\nfunction checkExamples(mediaType, location) {\n if (!mediaType?.schema) return;\n const validate = ajv.compile(mediaType.schema);\n\n const candidates =\n \"example\" in mediaType\n ? [[\"example\", mediaType.example]]\n : Object.entries(mediaType.examples ?? {}).map(([k, v]) => [k, v.value]);\n\n for (const [name, value] of candidates) {\n if (validate(value)) continue;\n for (const err of validate.errors ?? []) {\n console.log(`${location} example \"${name}\": ${err.instancePath || \"/\"} ${err.message}`);\n }\n }\n}\nRun it with additionalProperties: false asserted on the object schemas you own. Without that, an invented field is not an error to Ajv either — JSON Schema permits unknown properties unless the schema forbids them, so the invented loyaltyTier validates cleanly against a schema that simply never mentions it. That default is why \"we validate our examples\" is often true and worth nothing.
Three failures survive everything above, and each needs a different check rather than more of the same one.
\n\nA generated status enum lists PENDING, ACTIVE, CANCELLED, REFUNDED. The service emits PARTIALLY_REFUNDED as well. The enum is well-formed, and every example the model wrote validates against it, because the model wrote both. Nothing internal to the document can catch this: it is consistent with itself and wrong about the world. The only detection is replaying recorded production responses against the schema, which turns the missing value into a validation failure with a real payload attached.
A regenerated description differs from the published one in ninety places. Most are cosmetic — reordered properties, reworded descriptions. A few are a narrowed enum or a newly required request field, which are breaking for existing consumers. Reviewing the raw diff reliably produces fatigue and a rubber stamp by the fortieth hunk. Classify mechanically instead: compare the previous published artefact against the candidate and label each change additive, breaking, or cosmetic, then require a human decision only on the breaking set.
\n\nModels are consistently over-confident about required and about nullability, in both directions: fields that are always present get omitted from required, and fields that are frequently null get marked required and non-nullable. Both pass validation against examples the same model produced. Derive this from data rather than from the description — over a sample of real responses, a field present in every one is a required candidate, and a field null in any is not non-nullable, whatever the document claims.
One rule covers all three: no property of a generated description should be accepted because the description asserts it. Path parameters are the exception worth knowing, because there the specification does the work for you — for a parameter whose location is path, required \"is REQUIRED and its value MUST be true\", so a path parameter marked optional is a hard error rather than a judgement call.
No — edits are lost on the next generation. Put the corrections in the source the generator reads: route annotations, schema definitions, or a small overlay document merged after generation. Treat the generated file as build output and review it as you would review a lockfile diff, mechanically and by class of change.
\n\nIt removes the reconciliation problem and replaces it with a different one: the description becomes the thing nobody reads critically, because it is now upstream and therefore assumed correct. The security and domain-rule checks above still apply, and they matter more, since a mistake now propagates into the server rather than only into the documentation.
\n\nBlock on the mechanical ones with no judgement in them: an operation that removes or optionalises global security without an allowlist entry, an invented or undocumented route, a duplicate operationId, two path templates that differ only by parameter name, and a path parameter not marked required. Warn on the ones needing a human read — enum changes, required changes, and example mismatches — because those have legitimate cases and a blocking check with legitimate exceptions gets disabled within a month.
The security semantics are the same, and the reconciliation and example checks apply unchanged. The dialect handling differs: 3.1 aligns the Schema Object with JSON Schema 2020-12, so validate 3.1 schemas with a 2020-12 validator rather than the 3.0-flavoured subset. Ajv needs its 2020 build for that, which is the ajv/dist/2020.js entry point used above.
operationId uniqueness, the path-parameter required rule, and the SHOULD applied to examples.additionalProperties: false.security: [] lands in.Run the security posture script over your current published description before changing anything else. It takes a few minutes and it answers a question you probably cannot answer from memory: which operations have overridden the global requirement, and which of those are unauthenticated rather than merely different. If that list contains anything you did not expect, you have found the highest-value bug in this article without writing a test.
\n\nThen add two blocking checks to the pipeline — the security posture check with an explicit allowlist, and route reconciliation against the booted router — and keep the example and enum checks as warnings until you have seen a month of their output. The evidence worth retaining from each run is the reconciliation report itself: the two lists of invented and undocumented routes, dated, so drift between the description and the service is a trend you can look at rather than a surprise you discover during an incident.
\n\nOur JSON Schema Generator is useful for turning a handful of recorded production responses into the schema you compare the generated one against, and JSON Diff for separating the additive changes from the breaking ones in a regenerated description.
\n"}