Use API spec for actual route definition

[TitanNano]

We started to build our public API with axum and utoipa and are already facing the issue that we discover miss matches between the API spec and the actual implementation in axum.

Examples for this are, route path does not match utoipa path or method does not match utoipa path. For this reason, I started looking into what is being generated for the OpenAPI spec and how we could use that to avoid the drift between implementation and documentation.
What I found is quite nice, we can access the entire APS spec and extract all paths and methods from it to build our router. I discovered only two issues that block us from doing this, though:

1. there is no way of getting from the API spec to the correct handler function for axum. There is the operation id which by default matches the handler function name and with some macro magic, I might be able to locate the correct function, but I do not want to expose such an implementation detail in our public API spec. We would be depending on the operation id always matching the function name.
2. We are currently using route layer extensions to inject dependencies into our route handlers, and we will need some way of associating them with the path definition.

[juhaku]

This is quite hard problem to solve. Like I don't know a way to expose the path and request method from router or route function. Or the other way around how to generate a router or how to provide correct route definition from #[utoipa::path(...)] macro. The path macros are executed independently on compile time without any shared global data.

From #[derive(OpenApi)] we might be able to generate an axum Router but then a route_layer could not be used and instead regular layer should be used and then this router should be merged to the application router. Similary it could be possible to generate a list of route definitions of sort that then can be manually added to the axum router. These definitons could expose the path and the MethodRouter and then it would be a user choice to add correct route_layer with the path and MethodRouter.

After all this is something that could be really considered for inclusion to the library but is is axum specific functionality. This could experimented whether it would be possible in reasonable manner. And of course ideas related to the spec regarding how it should be implemented and what should be generated is appreciated.

[TitanNano]

I have given this more though and I think Utoipa does not have to build an Axum router. It rather should have the ability to provide an Axum Handler for an Operation. This could perhaps be done via an Axum-specific trait for Operations. The second thing would be a unique identifier for a path operation that is not a string and not publicly exposed, perhaps Utoipa can generate an enum of all the available routes and their operations?

[juhaku]

Hm.. sure, that is doable. It could be axum specific trait for Operations or to the OpenApi struct itself. On the second hand generating the identifiers can be done in utoipa-gen library so probably generating the route handlers could also be done there too.

I'll convert this to an issue so it get's tracked for progress. I cannot say when I get to look at this. But in sometime future the possibilities for this could be evalauated, tried out and eventually shipped.

[juhaku]

Now there is a WIP issue regarding this topic and it contains guidelines of the direction and the steps that are to be taken towards resolution. It can be found here #991.