search

juhaku / utoipa

Simple, Fast, Code first and Compile time generated OpenAPI documentation for Rust
Apache License 2.0
2.48k stars 197 forks source link

Using utoipa for Lemmy #662

Open Nutomic opened 1 year ago

Nutomic commented 1 year ago

Im a maintainer for Lemmy, which uses actix-web and has a large API of probably around 100 endpoints. I tried to integrate utoipa in order to generate API docs, as it seems like the best option in Rust.

Unfortunately this first attempt wasnt successful for a couple of reasons. Some of these have already been reported, but I thought makes sense to report these all together in context.

So the main problem is that a lot of information needs to be specified twice, once for actix-web and once for utoipa. This may work for a small project with a dozen API calls, but not when there are over hundred. It would be great if utoipa could parse the information from ServiceConfig instead (or provide a wrapper which passes route info to both actix-web and utoipa).

I hope this explanation makes sense, let me know if anything is unclear. You can also see the code with some comments here regarding these problems. I can also open separate issues for each item if desired.

Narven commented 1 year ago

Looks like a good crate, but no response from author in any way regarding issues. :( I dont know rust well enough to help

juhaku commented 1 year ago

These are very good points and good collection of things that needs or at least should be solved within some timespan. My goal for this is to have more automatic configuration than it currently has.

I get get that the double declaration is not feasible but I yet haven't find the time nor the perfect design on how to implement it that it would still be intuitive. There are 2 possible designs that I can think of, one where we implement custom ServiceConfig or Router that works as a bridge between the actual Router / ServiceConfig and same time maps the stuff to the openapi spec. Another one would be that the ServiceConfig or Router should be generated based on the OpenApi types. However this is still in early stages and PRs are of course welcome :slightly_smiling_face: One thing is sure, that implementing a ServiceConfig shim is a lot of work especially because it would have to be implemented to all supported frameworks, or then the framework support need to be reduced.

Automatic schema and path recognition is something that I have also been investigating and yes it could be a global vec but there is a catch, I am not sure how well that would work cross crates. Becuse some might have defined some types on another crate. That is a worth testing out (I guess). Currently there is one thrid-party crate that is actually working on solutions for this purpose https://github.com/juhaku/utoipa/discussions/635 as I have no time to do it all (at least that fast :laughing:).

But eventually yes, I also want this to be more thightly integrated with frameworks and all the help is welcome.

juhaku commented 1 year ago

To get back to this. At the moment probably quickest and easiest way to avoid duplication in OpenAPI path registeration is to manually implement the OpenApi with OpenApiBuilder and then along with that use PathBuilder to build paths. This should be used jointly with custom macro_rules which can be used to reduce boiler plate code. Some reference can be found here https://github.com/juhaku/utoipa/issues/230#issuecomment-1194689033.

juhaku commented 1 month ago

@Nutomic There is now coming support for actix-web::scopes and ServiceConfig with PR #1158 However manual routes are not supported as of yet, but the HttpServiceFactory style routes are.