Summary

Opening a new issue as discussed here.

From a DX perspective I personally find very helpful to have ordered routes in the Controller, that follow a certain logic:

• Progressive nesting (GET / comes before GET /:id and before GET /:id/nested)
• Logical actions ordering (GET, POST, GET id, PATCH id, DELETE id)

Example:

class MyController(Controller):
    tags = ["..."]
    path = "/"
    dependencies = {...}

    @routes.get()
    async def get_many(self):
        ...

    @routes.post()
    async def create(self, data: ...):
        ...

    @routes.get("/{resource_id:uuid}")
    async def get(self, resource_id: UUID):
        ...

    @routes.patch("/{resource_id:uuid}")
    async def update(self, resource_id: UUID):
        ...

    @routes.delete("/{resource_id:uuid}")
    async def delete(self, resource_id: UUID):
        ...

    @routes.get("/{resource_id:uuid}/nested")
    async def get_nested(self, resource_id: UUID):
        ...

Currently the ordering of the route definition at the Controller is not respected by the docs, so I end up having a Swagger that looks like this:

- GET /:id/nested/:nest_id/another
- POST /:id/nested
- GET /
- DELETE /:id
- PATCH /

Which I personally find very confusing since:
(1) It doesn't seem to follow a pre-defined logic (couldn't find any pattern for that when looking at the docs) it does seem to follow the ordering of the methods as defined here as shared by @guacs here
(2) It doesn't respect the logic that was defined on the controller (specifically the nesting).

Was having a quick look and it seems to be related to logic when registering the route here, and then the handler:method map on the HTTPRoute here.

It seems that by the time it reaches the plugin the nesting is already out of order - so it might make sense to handle when registering the routes maybe?

Anyways, if this is something of interest I'd help to contribute and take a deeper look into it.