Quick answer: Before adopting a scanned spec, review the detected routes rather than accepting the document as finished. Confirm each route is really mounted, read its gate status to distinguish proven values from gaps, and trace any unreachable or unmounted router. A detected route is a candidate grounded in code, not a fact you adopt without a check.
Why adoption needs a review step
The scan is deterministic and trustworthy within its limits, but it still produces a document for a person to confirm. Framework wiring can be missed, a route can be unreachable even though its code exists, and gaps can name unknowns you need to resolve. Adopting the spec without that review promotes the scan's output into a contract the team will build on.
The review is where you catch those issues before the document drives mocks, scenarios, and documentation.
What to check on each route
| Check | Question you answer |
|---|---|
| Mounting | Is the router actually mounted in the app? |
| Gate status | Are the contracts proven, proven-empty, or gap? |
| Reachability | Can the route be reached, or is it dead code? |
| Dependencies | Does it reference handlers or types that resolve? |
| Gaps | Which unknowns need a fill before adoption? |
A route that exists in code but sits behind an unmounted router is not a usable endpoint, even though the scan resolved its definition. Reachability is a separate question from detection.
A practical review sequence
- Read the project structure and note the detected routers.
- Confirm each router is mounted, and flag unmounted ones.
- Open the routes and check the gate status of their contracts.
- List the gaps and decide which need an AI fill or a manual fix.
- Confirm reachable routes before adopting the document.
- Re-run the scan after fixes and confirm the updates.
Tracing the callers and imports helps here, because a route that looks complete can reference a handler that does not resolve. The desktop shows the full source and the diff context, so you can read the code behind each detected path rather than a list of names.
Not every route needs the same depth. Start with the paths that carry writes, authentication, or money, because a wrong contract there has the largest blast radius, and move to read-only and internal routes after. A quick pass over the gate labels tells you where the gaps cluster, and a fully proven route can be skimmed while one with several gaps gets a full read. This keeps the review pointed rather than treating every path as equally risky, and it stops a large surface from turning the review into a slow, uniform slog.
Honest limits
The review cannot confirm runtime behavior by static reading alone. Even a fully reviewed route needs tests or scenario runs to verify how it behaves, and a successful scan still does not prove conformance. Keep model-only notes as hypotheses, and treat an unexercised path as unverified rather than safe.
Scenarios stay outside the OpenAPI document with no x-scenarios keys, and the spec you adopt is meant to feed that later verification rather than replace it.
Powerduck keeps the provenance and gate status on each route, so the review has the evidence it needs rather than a flat list to accept.
Frequently asked questions
Should I adopt the scanned document as-is? No. Confirm mounting and reachability, read the gate status, and resolve gaps before the spec drives mocks and scenarios.
What is the difference between a detected and a reachable route? A detected route is resolved in code, while a reachable one is actually mounted and can be called. Unmounted routers produce routes that are not usable.
Can a reviewed route still fail at runtime? Yes. Static review does not execute the behavior, so follow it with tests and scenario runs rather than treating adoption as verification.
The bottom line
A scanned spec is a draft grounded in evidence, and the review step is what makes it safe to adopt. Confirm every router is mounted and reachable, read the gate status rather than trusting blank-looking contracts, and resolve the named gaps before you build on the document. Keep runtime verification separate, since static review does not prove behavior. The scan hands you strong candidates; the decision to adopt stays with you. Read more in the code-to-OpenAPI guide.
