Skip to content

Extract built-in docs routes out of Quater #149

Description

@DevilsAutumn

Problem

Right now Quater is doing too much around built-in docs routes. If we open src/quater/app.py and check _builtin_routes, we can see that the app class directly registers the OpenAPI JSON route, Swagger UI route, Swagger asset routes, and MCP docs route.

The rendering code is already under src/quater/docs/, but the route setup and asset handlers are still methods on Quater. Because of this, any docs route change makes the main app class bigger and harder to scan.

Proposed behavior

Move the built-in docs route setup and Swagger asset handlers into a focused internal helper/module.

Quater should still expose the same behavior. OpenAPI path, Swagger docs path, MCP docs path, route names, auth metadata, and include_in_openapi=False behavior should not change.

This should also keep the existing tests passing for enabled docs, disabled docs, custom docs paths, Swagger assets, and MCP docs auth behavior.

Alternatives considered

We can leave this inside Quater, but the class already owns route registration, middleware, auth, actions, request handling, response handling, and built-in docs. Moving only docs route setup is a smaller cleanup than doing one big app refactor.

API sketch

app = Quater(openapi_path="/openapi.json", docs_path="/docs", mcp_docs_path="/mcp/docs")

The public API should stay like this. This issue is only about moving internal docs route setup out of the main app class.

Working on this?

Please wait until a maintainer marks the issue accepted. After that, comment before starting and make sure nobody else is assigned or already working on it.

Metadata

Metadata

Assignees

Labels

acceptedMaintainer accepted this issue for contributionenhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions