Feedback: Make the axum http server self-documenting with openapi/swagger like poem

[izelnakri]

Hi there,

First of all thank you for working on this project and showing your take to the world, I think its always useful even in the age of LLMs. Few years ago after trying poem rust lib, I've had an inspiration/discovery/epiphany that the future of http servers should be self-documenting: They should come with an openapi/swagger documentation by default(with /openapi or some other endpoint), without any annotation needed/required, annotations to give more context(like description to each endpoint etc) could be optional.

After I had that discovery I went on an investigation to see which rust libraries support this feature. Unfortunately no other library other than poem supports this feature out of the box, they all rely on middlewares that require optional annotations, thus they are not DRY. Last time I've checked, sadly axum also falls into this category.

I had managed to get the most minimalistic openapi integration to axum with utoipa, which was amazing API for writing detailed annotations that most http server middlewares utilize, however utoipa provides no way to make these openapi documentation generated from the code a developer has already written in an http server library. In other words, developers always duplicate code when they don't use poem API.

I see self-documenting http APIs to be the future of http server APIs. In JS world the thing that is close is NestJS however last time I checked it also required more decorators than it needed. Poem server API & annotations are close to perfection in this space. Could you make gerust web crates self-document openapi metadata/export /openapi.json by default(making annotations optional)?

I think this would be the biggest improvement for gerust and axum.

For more information on my "rather dismissed" proposal is here: juhaku/utoipa#1065 (comment)

[marcoow]

There's a WIP PR for that: #122