Open albert-una opened 7 months ago
I was hoping some community member would reply with a more "external" answer, but since there's none I'll give my 2c.
I am the current maintainer and unfortunately due to the lack of time I haven't got around to fix some of the bugs or add some of the features this crate is lacking. That being said there aren't many if any critical issues that I'm aware of (kinda of expected I guess, since paperclip is not involved in the "live" part, if that makes sense).
I've never used apistos so I can't comment on whether it's a better alternative or not.
Would I use paperclip myself? Yes and No :)
I haven't been using paperclip in my projects, not because of any issues but simply because I've flipped around and started using api first, so rather than generating openapi from code, I generate code from openapi. Paperclip already supports this but on openapi v2 only. I've tried to bring a new way though stuck atm due to licensing issues of the crate I was trying to use - https://github.com/paperclip-rs/paperclip/pull/506, at least until I find an alternative. If I was still generating api from paperclip I would probably still use paperclip, unless I needed to generate something openapi3 specific, which this crate is not supporting atm.
Thank you for this honest answer. And thank you for the time and work you put in this project!
While I would also be interested in hearing the more external answers you mentioned, I find it very interesting to read your point of view as well. I think it gives us a good insight of the current limits and of the potential direction this crate is heading to.
Since answers on this issue will probably be scarce and in case anyone finds themselves in a similar situation, I will try to summarize our current point of view of the problem.
We tried both crates (on very small toy projects) and it feels like switching from one to the other would not be that hard. So we can probably afford to take a chance and see what happens. As a result we are leaning toward giving apistos a chance at the moment (openapi3 seems to handle things like rust's algebraic enums better than openapi2 did).
I will try to keep everybody posted if we discover anything interesting along the way (or if we decide to switch to paperclip at some point)
First of all, I would like to make it very clear that I mean no disrespect with this issue. I use paperclip in several of my side projects and I am extremely grateful to its author, maintainers and community. It has served me well and I understand all the work that was needed to get it to this point.
However, my team is now starting a new web project, we opted for actix-web as our base framework, and I am trying to assess what would be the best candidate for documenting it. I tried utoipa but it is not what we are looking for since it mostly relies on endpoint declaration through macros which is probably fine for small projects but it is not what we want to rely on. It is also not as well integrated as paperclip may be.
That leaves us with two main contenders: paperclip an apistos. At first sight paperclip should be a no-brainer given how long it has been around and the size of its user base. But the project has been through some rough patches (with the original author stepping down etc.) and from a technical standpoint the project is still mostly generating swagger (v2) instead of openAPI v3. In the other hand apistos is still very young. We tested it and were happy with the result. But we are a bit worried it might not have enough traction on the long run.
Ideally we would simply wait a couple months to see what happens. But we need to make a decision in the next few days so that's not an option.
TL;DR here is my, admittedly tricky, questions: What would you do if you had to start a big project today? Do you think that paperclip will remain the go to solution for our use case or is it mostly in maintenance only mode with the community slowly moving away from it maybe to apistos or some other new crate we may have missed?