<rant>

I absolutely despise OpenApi(well, swagger. I’ll call it swagger since it was that for most of my career). It’s supposed to make the process of creating and documenting an API easier. But does it really?… Here’s what I think about it.

Writing the swagger schema is so damn tedious

From my experience when someone mentions swagger, you’ll get dragged into design first - code later mindset rather quickly. While it sounds good on paper the practical implications of writing a swagger schema just make me want to curl in a ball in the corner of the office. The swagger schema is so explicit and such a pain to write. We’ve got what I’d call a rather simplistic API by corporate standards at my work. I invite you to “design” it first. The swagger definition for it is 19808 lines long. I’m not kidding. Just think about it. 20 fucking thousand lines of JSON. Good luck designing that. Now, some of you will say “but wait a moment, why not generate the swagger schema from code”. While that does sound like a great idea on paper I really fail to see the point of it. If I document my code properly I can already generate documentation that is not going to be as tedious or as explicit. If the code is undocumented, swagger does not provide any sort of a benefit there.

Vik, you’re a scrub. It’s 2018 and you should be writing microservices. Then you’ll have no large swagger specs.

Well, how about no. I like my monoliths. I don’t scale apps that do not need scaling. It makes it easier to develop and maintain them. I’m not the only one.

Documentation

One of the main selling points for swagger is the fancy HTML documentation that you can generate from the swagger schema. In my experience, the documentation itself is absolutely and literally unusable. It makes perfect sense if you think about it. Most of the documentation is generated as static html from the swagger schema. Now take one that’s 20k lines long. If you expect it to be quick to load, fast to navigate and make sense of, I’d say you’re wrong. Add in all the “try it out live” web forms into it and you’re looking at a HTML page that your browser will refuse to work with in any way shape or form. All the interesting bits are the HTTP method, the URL and the payload model, anyway. Why have the extra details?

YAML sucks

Why the push for YAML in OpenApi? YAML is absolutely terrible and I’m a firm believer that it’s the case. Anything with whitespaces in it as a part of the spec is not human readable. If you have to differentiate between 3 or 4 spaces, how are you going to do it? I personally can’t. Maybe it’s just me but that’s a good enough reason for me. Tabs would help. Oh wait. JSON is also more compact. I like compactness. I’m a compact person myself(read: short). Also, yaml sucks.

Generating code from swagger spec

So you’ve got a couple of changes in the 10 billion line swagger spec. Time to generate code from it. Here’s what the next pull request will look like:

Good luck sifting through it. I for one, give up. I’ll give a more down to earth example with GO and go swagger lib. Let’s use the todo example yaml as input. I run the swagger server generation and here’s what the tiny pull request looks like:

2.8k lines of code. I know some of it is to blame on GO not having proper generics, but still. I hate it. I hate it so much…

Oh well, back to work. Back to fucking writing another path in that 10 billion line swagger.json.

</rant>

That being said, I’ve no better alternative at the moment.

What’s your stance on swagger? Do you use something else? What? Is there a better way to do this?