fix: enable mounting sub-applications under APIRouter

[jonathan-fulton]

Summary

Fixes #10180

When mounting a sub-application on an APIRouter with a prefix, the mount wasn't accessible at the expected path. The router's prefix wasn't being applied to mounts.

Changes

1. Override mount() in APIRouter to automatically apply the router's prefix
2. Handle Mount routes in include_router() to apply the include prefix

Usage

Enables patterns like:

router = APIRouter(prefix='/api')
router.mount('/subapp', FastAPI())
app.include_router(router)
# Sub-app is now accessible at /api/subapp/...

Note: Mounts must be added before include_router() is called.

Testing

Added comprehensive tests in tests/test_router_mount.py

[codspeed-hq]

Merging this PR will not alter performance

✅ 20 untouched benchmarks

---

_{Comparing jonathan-fulton:fix/issue-10180-router-mount (b641244) with master (c9629e0)¹}

Footnotes

1. No successful run was found on master (0892440) during the generation of this report, so c9629e0 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[YuriiMotov]

I think we should wait for Sebastian to take a decision on whether we want to support this.
I think we might want to support this for StaticFiles only..
Apps can be mount to the root app with prefix, and, IMO it will be clearer

[jonathan-fulton]

@YuriiMotov Thanks for the feedback! That makes sense - I'll wait for Sebastian's decision on whether this should be supported more broadly or limited to StaticFiles.

I agree that for full apps, using mount() on the root app with a prefix is cleaner. The main use case I was targeting was making it easier to mount StaticFiles under an APIRouter, which is a common pattern for organizing route groups with their own static assets.

Happy to adjust the scope based on Sebastian's guidance!

[YuriiMotov]

I think we might want to support this for StaticFiles only..

I implemented that approach in #13944

[abishekgiri]

One additional regression test that may be worth adding here is mounted sub-app OpenAPI behavior.

The original issue also mentioned docs/spec URLs, so it would be useful to assert that a sub-application mounted through APIRouter is reachable at its expected schema URL, for example /api/subapi/openapi.json when the router prefix is /api and the mount path is /subapi.

That helps verify not only request routing but also that the mounted app gets the correct composed path/root_path behavior.