search

ElektraInitiative / PermaplanT

https://www.permaplant.net
BSD 3-Clause "New" or "Revised" License
16 stars 13 forks source link

Consideration to move away from utoipa #1181

Closed Bushuo closed 7 months ago

Bushuo commented 9 months ago

Our current api documentation in the backend is done via utoipa. The process of documenting a new endpoint is currently very tedious and requires a lot of boilerplate. Errors are easily made by missing something somewhere which results in a broken swagger-ui. Did I mention the lots of boilerplate?

I was on the lookout for new solutions that integrate well into actix and found this article. The crate introduced there looks very promising and also looks a lot easier to handle.

https://medium.com/netwo/documenting-api-for-actix-web-b575adb841a1

https://docs.rs/apistos/latest/apistos/

What are your thoughts? @horenso @chr-schr @markus2330

markus2330 commented 9 months ago

Thx for sharing how we could improve.

requires a lot of boilerplate.

Is it "only" ugly and unpleasant or is it actually taking a lot of time?

Errors are easily made by missing something somewhere which results in a broken swagger-ui.

Broken at run time?

The crate introduced there looks very promising and also looks a lot easier to handle.

Thx for sharing! It seems to be a bit premature (at least one example seems to be wrong). Or what is your impression?

chr-schr commented 9 months ago

Until now I have not made many modifications to the API documentation, so I don't yet share your frustration. Personally I would be fine with either option. 🤷‍♂️

markus2330 commented 7 months ago

We stay with utopia for now.