I thought I was the only one! As far as I can tell the sentiment regarding Swagger/OpenAPI is generally positive, but I am starting to think that's just because it's an improvement over the status quo of "nothing" for most people.

I personally prefer API Blueprint, but even there is room for improvement.

I prefer RAML tbh - using Markdown as the basis of an API specification language is a pretty terrible idea. RAML's syntax is much more structured and pleasant, and the type syntax is far nicer to write than JSON Schema. Alas it seems to have lost the battle of network effects...

Maybe it's because the only APIs I've dealt with are kind of terrible, leads a bad taste in my mouth.

I would assume most people would use an extension to generate swagger off their endpoints on demand. Thats what I do in ASP.NET, via a library called Swashbuckle: Swagger and Swagger UI in three lines of code.

SOAP, WCF, CXF, et al, what’s old is new again.

It’s strange to have been playing this game long enough to see a full cycle.

Here be dragons.

Biggest difference continues to be the complexity of the client required. For HTTP webservices, its still a massive step forward.

What does the complexity matter? Either way you're running some service description file through some build tooling to generate some human unfriendly code. Who cares how big or complex the code in the middle is?

Because in most cases that I have experienced, no, you are not running the sdl through a generator to create a client. You are instead instantiating a http client, setting the right headers, urls, package bodies etc, all by hand. Something which is done in lieu of using a code generator because its trivial with an HTTP web service.

Furthermore, with an http api and depending on your security model, you can test/inspect a good portion of your APIs directly with a browser - a zero-cost client for all http apis that you get for free.

That is what tools like SoapUI are for.

Ah, the quixotic quest to square the circle, or in this case, design a language in which you can describe everything and yet everything is succinct.

ORMs and RPC / self-documenting API standards are like the Korean and Vietnam wars of programming.

You're not meant to write it by hand. I know you can, but why would you want that world of pain?

I have never felt the need to write swagger by hand, despite publishing a few API's in it. I always generate them directly from the domain code/function arguments.

It might be a benefit of statically typed languages though. I have no idea how you would automatically generate swagger from Javascript, without adding so much annotations that they become a poor man's types.

Swagger is typically used to auto-generate nice and interactive API docs automatically, not really meant to be written by hand.