Quick answer: Generating OpenAPI from an existing codebase means scanning a local backend and reverse-engineering a validated OpenAPI 3.2 document. Extraction is deterministic by default, proving routes through framework instance tracing and AST analysis rather than guessing, and a completeness gate classifies every parameter and response. AI only fills explicit gaps and cannot invent a route. This is a desktop-only Beta feature.
Why write a spec from code
Many working backends have no spec at all, or a spec that drifted away from the implementation long ago. Hand-writing one from memory is slow and tends to reproduce the same drift, because the author guesses at routes and shapes. A scan reads the actual code instead and builds the document from what it can prove.
The result is an OpenAPI 3.2 document, not a lowest-common-denominator version, so the spec keeps the dialect the code warrants.
The scan works on code you have locally, so it fits a backend you can open in the desktop rather than a service you only reach over the network. It reads the project structure and the framework wiring directly, and it excludes common dependency and build directories so the output reflects your code rather than the installed packages. Point the tool at the application entry point where the routers are assembled, since that is where the trace begins.
How extraction stays deterministic
The scan does not infer a route from a name that looks familiar. It proves routes two ways:
- Framework instance tracing, following the real app and router objects the framework wires.
- AST analysis, reading the syntax tree to resolve handlers and their paths.
Lookalikes such as cache.get(...) are not mistaken for route definitions, because the extraction follows the framework call rather than the matching word. This keeps the detected routes grounded in code that actually mounts them.
The completeness gate
Every parameter, body, and response is classified rather than left blank.
| Gate status | Meaning |
|---|---|
| Proven | The value is confirmed from the code |
| Proven-empty | The code confirms there is no value here |
| Gap | The scan could not determine it, so it is flagged |
A route is never emitted as a bare URL with empty contracts. The gate makes the unknowns explicit instead of hiding them, which is what keeps a generated document trustworthy.
Where AI is allowed to help
AI fills gaps with small per-handler slices tied to specific gap codes. It cannot invent a route, method, or path, and it does not replace the deterministic extraction. Source code is not sent anywhere by default, and a model key is not required for static scanning.
After the scan, you can review the detected routes before adopting the spec, and incremental rescans use a discovery.json sidecar while preserving your edits.
Honest limits
A successful scan is not proof that the implementation conforms. Treat unresolved findings as unknown rather than inferred facts, and remember that dynamic loading and framework entry points can still be missed. The scan rebuilds the contract from the code, but it does not certify the behavior, and it does not run the app.
Code-to-OpenAPI is a supporting capability behind the core workflows. It feeds a reliable spec that can later drive scenario tests, rather than being a reason to position the product as a general API tool.
Powerduck keeps the provenance of each route visible, so you can tell what the scan proved and what remains an explicit gap.
Frequently asked questions
Does the scan guess routes from names? No. Routes are proven through framework instance tracing and AST analysis, and lookalikes such as cache.get are not mistaken for routes.
What happens when a value cannot be determined? It is marked as a gap rather than left blank or invented. AI can fill specific gaps, but it cannot create a route.
Is a model key required to scan? No. Static scanning works without a model key, and source code is not sent anywhere by default.
The bottom line
Generating OpenAPI from code is a deterministic reverse-engineering process: framework tracing and AST analysis prove the real routes, a completeness gate marks every value as proven, proven-empty, or gap, and AI only fills gaps without inventing paths. It produces a 3.2 document you can review before adopting, while a successful scan still does not prove conformance. Its value is a spec grounded in the code, not a confident guess. Read more in the code-to-OpenAPI guide.
Top comments (0)