Oh, man. There is so much wrong with this article. Here we go:
> The documents are written in YAML, which I call XML for lazy people
No. That's ridiculous. XML (and JSON, for that matter) is designed to be read and written by machines, not humans. (If the design goal was actually primarily for humans to read and write it, the designers failed. Miserably.) YAML is a nice middle ground, in that it can be unambiguously parsed by a machine, but is also fairly pleasant and forgiving for humans to write.
> The enum thing
This is a problem with the code generators, not with Swagger as a spec. Any API definition format that allows enums (and IMO, all should) will have this "problem".
Language-native enums are way better to deal with than stringly-typed things. An alternative might be to generate the enum with an extra "UNKNOWN" value that can be used in the case that a new value is added on the server but the client doesn't know about it.
However, I would consider adding a value to an enum to be a breaking API change, regardless of how you look at it. What is client code expected to do with an unknown value? In some cases it might be benign, and just ignoring the unknown value is ok, but I'd think there are quite a few cases where not handling a case would be bad.
I agree with the author that "adding a new element to the structure of the payload should NEVER break your code", but that's not what adding an enum value is. Adding a new element to the structure is like adding a brand-new property on the response object that gives you more information. The client should of course ignore properties it doesn't recognize, and a properly-written codegen for a Swagger definition should do just that.
> Nobody reads the documentation anymore.
The author admits this issue isn't specific to Swagger, and yet harps on it anyway. What?
> No Hypermedia support ... Which means, you can change that business logic whenever you want without having to change the clients... Swagger is URI Centric
Oh god. I don't care what Roy Fielding says. No one has embraced hypermedia. It's irrelevant. Move on.
Being able to change biz logic has nothing to do with hypermedia. That's just called "good design". That's the entire point of an API: to abstract business logic and the implementation thereof from the client.
Regardless, the entire idea of being able to change your API without changing the clients is just silly. If you're changing the API purely for cosmetic reasons, just stop, and learn how to be a professional. If you're changing the API's actual functionality or behavior, the code that calls the client needs to know what the new functionality or behavior is before it can make use of it, or if it's even safe to make use of it. I imagine there are some small number of cases where doing this "automatically" is actually safe, but the incidences of it are so vanishingly small that it's not worth all the extra complexity and overhead in designing and building a hypermedia API.
APIs are not consumed by "smart" clients that know how to recurse a directory tree. They are consumed by humans who need to intelligently decide what API endpoints they need to use to accomplish their goals. Being able to write a dumb recursing client that is able to spit out a list of API endpoints (perhaps with documentation) is a cute trick, but... why bother when you can just post API docs on the web somwehere?
This section is irrelevant given my objections to the last section.
> YAML generation (default Java codegen uses annotations, codegen via this way will leak implementation details)
Well, duh, don't do it that way. Do API-first design, or at least write out your YAML definition by hand after the fact. If nothing else, it's a good exercise for you to validate that the API you've designed is sane and consistent.
> Swagger makes a very good first impression
Yes, and for me, that impression has mostly remained intact as I continue to work with it.
> What are the alternatives?
Having worked with both Spring and JAX-RS, I find it hard to take someone seriously if they're strongly recommending it as a better alternative to something as fantastic as Swagger. Also note that the author previously railed on the reference impl Java tool for its reliance on annotations... which... same deal with Spring and JAX-RS.