To all developers working on publicly visible APIs or writing public documentation.
DON’T BE A DICK !
Do not just put a screen capture of your curl request which takes 10 minutes to write by hand.
Do not show me list of arguments as an image.
Have AT LEAST one executable demo project (Any language)
And, it’s 2020, add a fucking proxy generator.
How hard can it be?

What is a proxy generator?

@zemaitis A server side component, usually paired with client side which generates the source code for all API calls.
Here is an example I’m using (Only c# or JavaScript tho) : https://github.com/RestCode/...
Basicly imagine scenarion where you want to connect to APIs, using this thing.
All you have to do is add reference to their generic client nuget and add config file.
It will at each build, go querry server and adapt your source code with API signatures.
Then when you want to use them you just write “thisApi.ThisMethod”. No manual management of URLs, request, GET/POST arguments.

I just publish swagger metadata and an interactive ui. If people can't figure out how to gen a language-specific client from that, fuck 'em.

@SortOfTested Yes, but you use swagger. Which already has support for meta data.
I will be perfectly fine with that !
But it’s not the case for like 90% of companies.
(PS : I use the one I provided as we custom it a bit ;p basically it matches our TypeScript definitions of classes/namespace in local, but provide “right” namespace in remote)

A bit funny, but XML-RPC provided exactly that.

@sbiewald
Yeah, it's a continuous cycle:

- new tech reduces tedium
- new tech has insufficient metadata
- metadata added to tech (SOAP, in that case)
- new tech has too much tedium
- next tech replaces new tech, bc easy
- next tech has insufficient metadata...

Hmm no.

My job is it to develop an api and document the api. Not develop the client some dude wants to generate. If I use swagger to document the api then your in luck. Or not. Because I know that the generator is fucking garbage and doesn't work.

Also my demo project would be in bash. So it's curl commands again :P

@sbiewald WSDL too :)

@fuckwit

Then, i’m sorry, you are a worst developer type existing : you don’t care one bit about others.
It will take you about a day to add all of what I mentioned.
By NOT doing that (Cause it’s not your job) you are wasting multiple DAYS of EACH developer using your services.
So yeah, keep being a dick to others.

@NoToJavaScript I just don't want to support something that I know doesn't work. Simple as that.

Look let's take rust as an example:

Rust has many different libraries for making HTTP requests. There's reqwest, ureq, curl, isahc, attohttpc, minreq, awc and a lot of others. Then some of them only work in sync rust some in async rust and some on both. Oh and what async runtime should it generate the code for? Async_std or Tokio? Also some of those http libs word on in environment where no standard library is present (embeded devices for example).

Now those are a lot of parameters a generator simply can't take into account.
Also I haven't even gotten into the totally not idiomatic code that generator generates.

As I said I mostly use swagger to generate my docs and if it shoul by any chance generate working code that you feel good using. Well have fun. But don't come to me and complain about a broken client.