I inherited a legacy FastAPI application with approximately 10,000 lines of code across a deeply nested module structure. The API routes were fragmented, Pydantic models were defined ad-hoc, and dependency injection was used inconsistently. My goal was to use Cursor's AI features to generate comprehensive documentation without manually tracing every import.
I started by opening the project root in Cursor and using the `@doc` command in the chat panel with a broad prompt: "Generate an overview of this FastAPI application, listing all top-level routes, their main models, and key dependencies." The initial output was a decent high-level summary but missed many nested routers.
The real test was using Cursor's "Explain this codebase" feature from the project panel. It produced a structured markdown file. Here's a snippet of what it captured well:
```markdown
## Key Routes
- `/api/v1/users` (GET, POST) -> `app.routers.user_v1`
- Uses `UserCreate` model from `app.models.user`
- Depends on `get_db` session
- `/api/v2/orders/complex_query` -> `app.routers.v2.orders.subrouter`
```
However, the analysis had clear gaps:
* It correctly identified 14 top-level routes but missed 7 that were dynamically included via a helper function.
* It generated code blocks for 23 Pydantic models, but 5 were duplicates with slight variations it didn't flag.
* It failed to trace the flow of a critical, custom `Authorize` dependency through more than two levels.
To get usable docs, I had to run several targeted queries:
- "Find all uses of the `PaymentService` class and list the routes that inject it."
- "List all Pydantic models defined in the `schemas` directory and show which routes use them as `response_model`."
The final documentation is serviceable for a new engineer onboarding, but it's a snapshot, not a living doc. It required significant human guidance to correct the AI's assumptions about our project structure. The process saved me perhaps 40 hours of manual work, but the output is a static artifact that will drift from the code immediately.
Key takeaways for using Cursor on large, messy codebases:
* Its cross-file understanding is good but not omniscient; dynamic or metaprogramming patterns break it.
* You must iteratively refine your prompts with specific class and file names.
* The generated docs lack any inherent "update" mechanism. This isn't Cursor's fault, but it limits the long-term value.
* For a truly maintainable API doc, you'd still need to integrate a tool like FastAPI's own OpenAPI generation or Redoc alongside this.