The UI is (mostly) done, now it's time to flesh out the API!

Just discovered Insomnia Designer, I freaking love it and it's git integration. This is exactly what we developers needed for years 🥳

Dear API vendor,

Please get off your arse and learn about REST, OpenAPI, JSON Schema, XSD and basic documentation so that I don't have to guess how to use your shitty, inconsistent, RPC over HTTP service.

With Love,

Platypus

!rant
Just tried Vapor (server side Swift) for a web api project and expected to be troubleshooting a lot but it was super easy and worked out of the box. Even openapi/swagger generation.
Now I‘m exited to build a fullstack project with native and web clients, completely in Swift. 😁

Why does every other tool in npm wants to litter their own stupid configuration file at my project root?

When you're using openapi generators and stuff for generating SDK code and let "the architect" handle the data structure and nomenclature, don't you hate having to add 33 (I counted) models, most of which are just the same class with different name or one property apart from each other, serialization of which gives request body overhead 56-132x (actual calculated results depending on the model complexity) the size of actual data you want to send, just to add support for one endpoint that needs just one model that started this whole madness?
I just had to add this one top level model reference and this happened to me. Those 33 models are not including the ones I already had included in my project so they didn't have to import them again.
For the love of <your_belief_here /> and all that's holy, never ever agree on generating code based on openapi if the person responsible for that is unexperienced. It will do more harm than good, trust me.
Before we decided to go with generated SDK my compiled product was a bit over 30KB, and worked just fine, but required a bit of work on each breaking API change. Every change in the API requires now 75% of that work and the compiled package is now over 8MB (750KB of which is probably my code and actually needed dependencies).
Adding an endpoint handler before? Add url, set method and construct the body with the bare minimum accepted by the server
Now? Add 33 models (or more), run full-project find&replace and hope it will work with the method supplied by the generated code, because it's not a mature tech and it's not always guaranteed it will work.

In a normal application with front and back separated, how do you guarantee consistency between models? Do people normally do PRs to change them on both sides and hope none screws up or is there a better way?

Some time ago I was looking into generating stuff from the OpenAPI spec. Is this a good idea? Also, can graphql help with this? I'm soooo confused by this, it's like a problem I never managed to solve in my head...

What tool do you use for API documentation, and why? OpenApi (Swagger) or RAML or anything else?