Runtime vs OpenAPI
OpenAPI is a claim. The framework registration is evidence.
An OpenAPI document can omit a route the process is serving, or describe a route the process never registered. Reading the document cannot prove what the framework registered. FlexDoc reads both, on Node, Spring MVC, and ASP.NET Core, and reports the disagreement.
What FlexDoc observes
Runtime Intelligence reads the routes the running framework registered: the Express, Fastify, Hono, or Nest router, Spring RequestMappingHandlerMapping, or the ASP.NET Core EndpointDataSource. It records the method and path. It does not invent a handler, schema, parameter, or auth scheme for a route the contract does not describe.
Complete and partial discovery
Complete discovery means the inventory was readable. An unacknowledged runtime-only route is then an error. Partial discovery means the inventory might be incomplete, so that same route is a warning. Absence claims stay marked incomplete instead of being guessed.
The findings
runtime.operation-undocumented— the framework registered a method and path that OpenAPI does not declare.runtime.operation-unobserved— OpenAPI declares an operation the runtime inventory does not contain.runtime.method-mismatch— the path is present, and the methods do not agree.- Path-parameter names are the same wire shape.
{id}and{petId}are one route.
Acknowledgement
Acknowledgement is a policy, not a deletion. An acknowledged undocumented route stays in the runtime record. The finding stays, at info severity, and it does not fail the check. GET /internal/health can be acknowledged. POST /internal/reindex, left unacknowledged, fails a complete-discovery check.
From the finding to a request
Opening the finding shows that OpenAPI does not declare the operation beside the method and path the framework registered. Open in API Client sends that method and path. The URL is the runtime snapshot origin plus the runtime path. FlexDoc does not substitute an OpenAPI server for a route the contract does not describe.
flexdoc validate
The CLI reads the same validation object the backend produced. It exits 1 when the status is fail. Warnings and informational acknowledgements do not fail the command unless you pass --fail-on warning or --fail-on info. If the snapshot has no validation object, the CLI does not invent one.
FastAPI can show which routes Starlette registered. It does not emit this validation object, because its OpenAPI document is usually generated from those same declarations.