
Problems with Swagger - senand
http://blog.novatec-gmbh.de/the-problems-with-swagger/
======
gkoberger
My problem with Swagger is almost the opposite... it solves the problem (APIs
are very complicated to use!) by embracing this complexity with more
complexity and more tools. Rather, I believe the solution is a push to just
have simpler APIs.

It's crazy to me that it's harder to write a Swagger file than it is to write
the API itself. And there's a lot of tooling that benefits from Swagger,
but... I've found they all work 80%. Codegen, documentation, etc get 80% of
the way there.

(Also, OAS 3 has linking, which is very similar to your hypermedia complaint)

~~~
mcescalante
I had these same issues. It took me considerably more time and effort to write
a Swagger spec and get the UI to actually behave than it did to write my
entire API and some simple docs in markdown.

I also tried out the "codegen" and a few other projects that generate
boilerplate from a spec (for Python) - the code it generated was frustrating,
lengthy, and much more complex than the simple endpoints that I quickly wrote
from scratch.

~~~
eropple
_> It took me considerably more time and effort to write a Swagger spec and
get the UI to actually behave than it did to write my entire API and some
simple docs in markdown._

How long did it take to write API consumer libraries in twenty languages and
update every one on API change?

If you don't care about that, then Swagger isn't a good idea for you. But I'd
think really hard about whether you _should_ care about it if you think you
don't.

 _> the code it generated was frustrating, lengthy, and much more complex than
the simple endpoints that I quickly wrote from scratch_

Sure--but you didn't have to write it.

~~~
pbreit
Is whatever value people are getting out of client libraries provided by
something generic like [http://unirest.io](http://unirest.io) ?

When does it make sense to issue API-specific client libraries for a plain ole
RESTful API?

~~~
eropple
_> When does it make sense to issue API-specific client libraries for a plain
ole RESTful API?_

Any time you have a statically-typed language consuming you. Having to write
my own Jackson declarations to pull in your API to a JVM project or my own
DataContract barf for a CLR one is a quick way to make me hate you, and me
hating you means I'm already looking for an alternative that isn't you that
gets out of my way.

~~~
pbreit
I sort of thought the opposite, that the client libraries are what is getting
in the way.

~~~
eropple
So you enjoy writing a bunch of boilerplate class files that are manual
translations of somebody else's doc?

~~~
pbreit
No, I just like to get started coding API calls.

------
mr_tristan
I've found swagger codegen to be really, really inconsistent between different
implementations. A few of them - I recall we had a team using Qt - didn't even
generate compilable code. When I looked into the infrastructure of the codegen
project, I found... mustache.

Check it out yourself: [https://github.com/swagger-api/swagger-
codegen/tree/master/m...](https://github.com/swagger-api/swagger-
codegen/tree/master/modules/swagger-codegen/src/main/resources)

Mustache is fine for doing a little view rendering, but for language
generation... it's really obnoxious to use. Say you want to customize the
output. Well, now you're basically replacing one of those magic .mustache
files. And what's the model you use to generate those mustache files? Well,
you got to look through the codebase for that.

I ended up just not using swagger-codegen, and created my own StringTemplate
based system, which got the job done a lot faster. The swagger core model was
really janky to build logic around, however, so this system was really
implementation specific.

In the end, were I to do it all over again, I would have probably just built a
different mechanism. And honestly, building your own damn little DSL and code
generators for your use case will probably be faster then integrating Swagger.
_Especially_ if you do not use the JVM as part of your existing toolchain.

I've not found anything to support multiple languages easily. If I were to do
something today, I'd probably create a custom API DSL, custom code generators,
with an output for asciidoctor (which is awesome) and example and test
projects that test the generated code. Once you get the pipeline going the
work is pretty straightforward.

~~~
wing328hk
> I've found swagger codegen to be really, really inconsistent between
> different implementations. A few of them - I recall we had a team using Qt -
> didn't even generate compilable code. When I looked into the infrastructure
> of the codegen project, I found... mustache.

Yup, some generators (e.g. ActionScript, Qt5 C++) are less mature than the
others (e.g. Ruby, PHP, C#). For the issues with Qt5 C++ generator, please
open an issue via [http://github.com/swagger-api/swagger-
codegen/issues/new](http://github.com/swagger-api/swagger-codegen/issues/new)
so that the community can help work on it.

> Mustache is fine for doing a little view rendering, but for language
> generation... it's really obnoxious to use. Say you want to customize the
> output. Well, now you're basically replacing one of those magic .mustache
> files. And what's the model you use to generate those mustache files? Well,
> you got to look through the codebase for that.

Instead looking through the codebase, you may also want to try the debug flag
(e.g. debugOperations, debugModels) to get a list of tags available in the
mustache templates: [https://github.com/swagger-api/swagger-
codegen/wiki/FAQ#how-...](https://github.com/swagger-api/swagger-
codegen/wiki/FAQ#how-to-debug-swagger-codegen)

I agree that mustache may not be the best template system in the world but
it's easy to learn and developers seem pretty comfortable using it.

> Especially if you do not use the JVM as part of your existing toolchain.

One can also use docker ([https://github.com/swagger-api/swagger-
codegen#docker](https://github.com/swagger-api/swagger-codegen#docker)) or
[https://generator.swagger.io](https://generator.swagger.io)
([https://github.com/swagger-api/swagger-codegen#online-
genera...](https://github.com/swagger-api/swagger-codegen#online-generators))
to leverage Swagger Codegen without installing JVM.

Thanks for the feedback and I hope the above helps.

(Disclosure: I'm a top contributor to the project)

~~~
gregopet
Mustache is the most limiting (not to mention ugly) template language I've
seen in a long time. It allows no logic whatsoever and even writing simple if
statements is tedious. We have a Swagger spec from which we generate
Asciidoctor documentation via a Gradle plugin which works very nice, and
generate basic POJOs for Java and POCOs for C#. That... does not work very
well for our purposes.

We wanted to produce named enumerables by using custom extensions and found no
way of doing it with Mustache. It didn't help that our custom extension YAML
was passed into Mustache as serialized JSON. One of our developers took it
upon himself to make it work and ended up writing his own simple version of
the Codegen which works well enough for us. He tried modifying one of the
backends preparing data for Mustache but then said rewriting it on his own was
just simpler.

------
hjacobs
While Swagger might not be perfect (some pain points are addressed with
OpenAPI v3) it works IMHO pretty well for us (Zalando) and myself doing API
first:

* use a decent editor to write the YAML e.g. [https://github.com/zalando/intellij-swagger](https://github.com/zalando/intellij-swagger) * do not write any boilerplate code and do not generate code (if that's possible in your env), e.g. by using [https://github.com/zalando/connexion](https://github.com/zalando/connexion) (Python API-first) * follow best practices and guidelines to have a consistent API experience, e.g. [https://zalando.github.io/restful-api-guidelines/](https://zalando.github.io/restful-api-guidelines/)

Most importantly Swagger/OpenAPI gives us a "simple" (everything is relative!)
language to define APIs and discuss/review them independent of languages as
teams use different ones across Zalando Tech.

~~~
cimi_
Easy is subjective, simple is objective. You probably meant easy ;)

------
Yhippa
I really like the idea of HATEOAS but I have never seen hypermedia controls
done in the wild across any companies I've worked for nor on any client
projects. I think it's very cool but a lot of development patterns don't
consider it.

~~~
richardwhiuk
I agree that HATEOAS is never deployed anywhere, but I think I'd go further
than that.

It's impossible for me to see how it would be possible to write a HATEOAS
client, and I can't in practice see anyone doing so.

Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong
metrics, and a complete waste of development time and effort.

~~~
querulous
every web browser you use is a hateoas client

you get some html with embedded links and then the browser automatically goes
and fetches css, js, images...

the remaining links it just presents to you, the user, to follow or not as you
choose

hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or
thrift. it's something else

~~~
ajross
Except the browser really isn't. It has strict behavior, and the list of what
happens as it loads that hypermedia is deterministic and known to both the
client and server. The difference between what happens when the browser sees a
"stylesheet" link reference and a "icon" one is significant, and not something
the browser is expected to figure out on its own.

The HATEOAS idea is that you throw that out, just use some aribitrary XML
(sorry, "hypermedia") to return your application state, and that this somehow
magically empowers the client to be able to puzzle out all the things that can
be done to your state.

Except it can't. It's just arbitrary junk if you don't have a schema and a
spec. And it will always be so. Discoverability is (1) not something you can
get from a data structure and (2) something best provided by documentation,
not runtime behavior.

~~~
icebraining
I think you have a completely wrong idea about HATEOAS. The application is
certainly expected to be able to handle the data format, not figure out by
magic. As Fielding writes in his dissertation, _REST components communicate by
transferring a representation of a resource in a format matching one of an
evolving set of standard data types_. The client is certainly supposed to
understand these data types, that's why they must be standard (like HTML). The
dynamic part comes from the formats themselves, which may have variable or
optional elements depending on the state of the resource.

~~~
ajross
Someone needs to fix the wikipedia page on HATEOAS then, because it says
exactly the opposite of what you just did in its third sentence.

(One of the other problems with Fielding's work is precisely this word-salad
of new jargon and usages, leading to exactly this kind of what-does-it-REALLY-
mean-anyway confusion. But that's an argument for a different thread.)

~~~
icebraining
From the wikipedia page: _" The media types used for these representations,
and the link relations they may contain, are standardized."_

As for Fielding's work having a word-salad of new jargon and uses, I frankly
didn't get that by reading his dissertation, which I found quite clear. There
are a few concepts (Resources, Representations), but I think they make sense
in the context.

------
int_19h
TL;DR version:

The first problem is that Swagger encourages codegen, and in static languages,
said codegen is often unnecessarily restrictive when parsing input data.
Adding a new enum member, and what that does to an existing Java client (that
maps it to Java enum, which now has a missing member), is given as an example.

The second and third problems are actually one and the same, and that is that
Swagger doesn't do Hypermedia. If you don't know what that and HATEOAS is,
this entire part is irrelevant to you. If you do know, and you believe it's a
fad, then you wouldn't agree with any points in that complaint. If you do know
and like it, then you already know what it is about (it's basically just
rehashing the usual "why HATEOAS is the only proper way to do REST" narrative,
with Swagger as an example).

The last problem is that if you do API first (rather than YAML first), it's
overly verbose, and can potentially leak implementation details into your
spec.

~~~
jayd16
At its core, the complaint is just sour grapes from not planning ahead. You
wrote the API with the guarantee of an enum, and then broke the gurantee and
expected all the code relying on that guarantee to be fine. It doesn't work
that way.

~~~
int_19h
Not quite; the point it's trying to make is that having an enum is not
necessarily a guarantee that no new members will be added in the future, or at
least it shouldn't be.

I think it's half-right, in a sense that this is true for enums that are used
for input values only. If the API adds a new enum value, it can also add
handling for that value, so existing clients should just work (they just never
use that new value). But if the enum is present in any output data, then
adding a new value to it is a contract break, because existing clients can see
it, and they don't know what they're supposed to do with it.

------
misterbowfinger
This seems more like, "issues with how Swagger is used in Java". A lot of Java
developers are used to the SOAP APIs of yesteryear, and thus try to create
clients with Swagger when they should be using gRPC or Thrift.

In other language paradigms, I haven't faced this issue. Swagger is _just_
documentation, and a nice front-end on top. The Java annotations definitely
make it easy to generate, though, I'll give it that.

~~~
cookiecaper
Thrift and protobufs are underappreciated. Better integration in something
similar to the Swagger Editor would give these a much more comfortable home
and allow them to see adoption in the web world, where people generally expect
things to be a little softer.

I've never really liked the REST paradigm, so I'd be pleased to see it die.

My biggest complaint with Thrift: they still make you do some convoluted hacks
to get a two-way ("streaming") connection in the RPC, and when this is
discussed, they usually kibosh it pretty quickly by saying it's an unsupported
case and that you can find some hacks online, but they don't want to talk
about it any further.

This may not have been a big problem for them before gRPC was released for
protobufs, but it's definitely something that's worthy of attention and
response now. I know lots of people who are going with protobufs instead
because of this.

The other thing is that while Thrift boasts a lot of language compatibility,
several of these are buggy.

~~~
jessaustin
_I 've never really liked the REST paradigm, so I'd be pleased to see it die._

Don't hold your breath. Fielding's thesis is already 17 years old, so one
would expect its philosophy to endure by the Lindy Effect if for no other
reason.

~~~
cookiecaper
If the "Lindy Effect" was a natural law and not simply a shorthand to refer to
enduring popularity, nothing would ever die out; its lifetime would
continually double. Wikipedia notes this: _Because life expectancy is
probabilistically derived, a thing may become extinct before its "expected"
survival. In other words, one needs to gauge both the age and "health" of the
thing to determine continued survival._

There are lots of things in tech that we just stop doing one day. They get
replaced by a different hot new thing. I'm sure REST will not go extinct for a
very long time, but it definitely _could_ go cold, just like its popular
predecessors.

~~~
emmelaich
Perhaps REST as the thing you do over http with http verbs won't be around.

But the architectural principle called REST will be around forever because
it's essentially the same thing as functional programming.

That REST is cache friendly corresponds exactly to the way that pure functions
are memo-ising friendly.

------
dandlift
In my team we established a process where our first step is to write down the
spec of the API, in swagger format.

The spec is the source of thruth, and is written manually in yaml (that's not
that painful). The implementation comes later. Unit tests check that it
conforms with the spec. [1] We also have a fake API almost completely
autogenerated from the spec that's quite useful for preliminary testing of the
clients.

Client code generation wasn't up to my expectations, but I've experimented
with applying an handwritten template to a parsed spec and that seems viable.

Swagger as a format might have its quirks, but the tooling is there and having
it as the authoritive source of thruth paid off for Us.

[1] [https://bitbucket.org/atlassian/swagger-request-
validator](https://bitbucket.org/atlassian/swagger-request-validator)

------
badreaction
We use swagger heavily and I can say the following: 1) We use the tolerant
reader pattern. It is entirely possible to generate tolerant client code where
the enum and adding new element does not cause issues. The problem here is not
swagger but poor code gen.

2) We use hypermedia in all of our APIs extensively, I don't see how this is
impacted by swagger? Hypermedia is a runtime discovery mechanism and so other
than declaring the link structures in your schema, has no place in swagger. We
don't use HAL, and wouldn't recommend it either.

~~~
daenney
Totally agree on the codegen bits.

> To mitigate this problem just stop generating code and doing automatic
> deserialisation. Sadly, I have observed that’s a very hard habit to break.

That conclusion really irks me. In Java, if you're using AutoMatter for
example, you're one annotation away from discarding unknown fields and many
other serialisation frameworks offer the same ability. It's not a default
(which imho it should be) but it's trivial to fix.

------
throwaway2016a
I'm surprised RAML isn't suggested as na alternative.
[http://raml.org/](http://raml.org/)

~~~
misterbowfinger
Does it address the issues in the post?

~~~
jstoiko
The RAML 1.0 type system can help:
[http://adrobisch.github.io/blog/articles/hateoas-with-
raml-1...](http://adrobisch.github.io/blog/articles/hateoas-with-raml-10.html)

------
bluejekyll
> To mitigate this problem just stop generating code and doing automatic
> deserialisation.

No! WTF?! Just use generators that produce code that is resilient to a
changing API. Why would you get rid of a huge productivity boost because the
generator doesn't produce code you like? That's trading two hours of work to
change the generator, for many multiple hours of reproducing the proper API,
especially if you have many to support.

I stopped reading right there. My personal biggest issue with swagger is that
they threw the baby out with the bath water, reproducing XSD in Yaml, for no
good reason. The UI they produced was nice, and that is probably the best
feature of swagger. But the data format doesn't solve a new problem IMO, it
just created a new standard that we all have to deal with.

What is that now? Corba IDL, XSD, protobuf, thrift, avro, Swagger, Raml... I'm
sure because of the flaws in each of those, we really should just use the new
OpenAPI.

Or just get rid of them all and go bare metal with Cap'n Proto. Oh but don't
use code generators for any of those, because that would make it way too easy
to support all of them with a single API </sarcasm>.

------
prodikl
> The rest of the URIs are provided by Hypermedia.

I know this sounds awesome but in practice, it's really useful to have my
swagger UI exposing the endpoints for our front-end developers to consume.
What a pain it'd be for me to tell them "hit / and see what you get!"

Having HAL links between resources is great and this discovery aspect of
HATEOAS makes a lot of sense in development. But having a single entrypoint
"homepage" to the API, when it comes to swagger, doesn't make sense.

I ran into this when I asked another department for the endpoint to hit for
certain data. I was given a swagger page with a bunch of "/status" endpoints
that would then reveal additional endpoints. Who knows what rabbit hole I was
sent down. I just needed the endpoint and the necessary parameters.

If I were a third party or some outside developer consuming the API, it kind
of makes sense. But our internal swagger docs really should reveal endpoints.
I would feel like a big asshole if I asked my front-end co-worker to just "hit
/status" and see if you get what you need!

Disclosure: I don't use Swagger codegen. I only use the Docblock markup to
document my API and generate the swagger.json that I display on our docs page.

------
daliwali
An alternative is to just ditch these complicated documentation formats
altogether. Put down your pitchforks, I'll explain.

The author of REST, Roy Fielding stated that only the entry URL and media type
should be necessary to know in advance. Swagger would be considered out-of-
band information, if it's necessary to have this documentation beforehand then
it doesn't follow this constraint. Interactions must be driven by hypermedia,
an idea which has a very unmarketable acronym.

The alternative that is suggested is to _document media types, not APIs_. If
HTML were not a standard and every web page had to define its own technical
specifications, the web wouldn't have taken off, because it wouldn't have been
interoperable. Interoperability is key, it reduces friction from transitioning
between web pages on different servers. How HTTP APIs are built today is
wasteful, there are vendor-specific tooling costs up front and it doesn't
scale.

~~~
jshen
What is an example of a well done API that functions the way you describe?

------
ogrim
I would never write Swagger by hand; why should I when I can have it
generated? We are using Swashbuckle[0] to generate Swagger for our ASP.NET Web
API, which have been a great experience. We can explore and test the API in
Swagger UI. I have been sprinkling a bit of hypermedia on top of this with
HAL, mainly just for having links. I have never met anyone wanting to go the
full HATEOAS route, but simple links can go a long wa. Swagger UI have been
great for this, as HAL alone isn't really expressive enough to document what a
link means. On the consumer side, I have been using NSwag[1] to generate
clients with good results.

[0]
[https://github.com/domaindrivendev/Swashbuckle](https://github.com/domaindrivendev/Swashbuckle)
[1] [https://github.com/NSwag/NSwag](https://github.com/NSwag/NSwag)

~~~
eddieroger
> why should I when I can have it generated?

Because maybe you work on a team where half are creating an API and half are
creating a client, and if you write a Swagger spec first, you can both be
working at the same time, against the same contract, and just meet in the
middle? And if you're working on the consumer side of things, you can take
that spec and stand it up against a mocking engine that will now give you
something to test against while your API team finishes their work? Just
because you would rather generate Swagger doesn't mean there's not a reason to
write it by hand before writing code.

~~~
ogrim
One can still do what you are describing and have the Swagger spec generated.
On my platform, I would just specify data types and the interfaces, and have
Swashbuckle parse this and spit out the Swagger spec. No need to hand-code
Swagger while creating the contract up front. After this step, one could work
at both sides of the contract independently as you describe.

------
Touche
So many problems in programming are caused by trying to replace code with
configuration. I've learned over time that the DRY principle can be harmful.
Avoiding repetition is only good when it remains equally readable and
powerful.

Defining a DSL is almost alway a better idea (but more difficult) than
defining a configuration format.

~~~
carapace
What is the difference between a DSL and a configuration format?

I mean the _essential_ difference. ;-)

------
beders
People often don't make a crucial distinction: Are you developing an API that
happens to be accessible via HTTP or are you developing a Web Service.

For an API where you control both the server and the client, you don't need to
use REST.

For a Web Service, where you don't control which clients are using, you are
better off with a RESTful implementation supporting hypermedia. Especially if
you are interested in keeping clients happy and not give them the middle-
finger shaped like a incompatible-v2 version of your service.

------
api
API Blueprint is much, much cleaner:
[https://apiblueprint.org](https://apiblueprint.org)

Here's a renderer:
[https://github.com/danielgtaylor/aglio](https://github.com/danielgtaylor/aglio)

It's less feature-rich than Swagger but the format is much less of a
nightmare.

------
banachtarski
I stopped reading after the author's silly interpretation of enums and why
they "weren't" useful. The rantings of a beginner don't make for a good
critique.

------
carapace
I read "YAML, which I call XML for lazy people"... and closed the tab.

~~~
borplk
why?

------
Vinnl
So here's something I've never quite understood when reading about HATEOAS:

> Without hypermedia, the clients would probably have to parse the payload to
> see if there are some kind of status and then evaluate that status to take a
> decision whether the order may or not be canceled.

In the given example, wouldn't the client still need to check whether there
actually is a `cancel` link (and know that it _can_ be there), and decide
whether or not to call it? In other words, isn't it unavoidable that there's
business logic in the clients?

------
buremba
"..swagger repeats itself a lot with redundant annotations, it also leads to
having more annotations than actual code."

(Shameless plug) For this exact problem, we developed a Java library that
makes easy to create RESTFul services that's highly integrated with Swagger.
Here it is: [https://github.com/buremba/netty-
rest](https://github.com/buremba/netty-rest)

We also tried hard to stick with Swagger-codegen but it's far from being
stable so eventually we ended up creating a Slate documentation that
demonstrates the usage of API with high level HTTP libraries for various
programming languages.

We convert Swagger spec to HAR representation, create the example usage of the
endpoint with httpsnippet from the HAR
([https://www.npmjs.com/package/httpsnippet](https://www.npmjs.com/package/httpsnippet))
and embed it in our Slate documentation using our Slate documentation
generator. ([https://github.com/buremba/swagger-
slate](https://github.com/buremba/swagger-slate))

Here is an example: [http://api.rakam.io/](http://api.rakam.io/)

------
hodgesrm
> The original problem swagger tries to solve is: API documentation. So, if
> you need to document an API, use a format that is created for that purpose.
> I highly recommend using Asciidoctor for writing documentation. There are
> some tools for Java that help you with this. However they are somehow
> technology specific. For instance Spring REST Docs works very well if you
> are using Spring / Spring Boot.

I have used Asciidoctor + Spring REST Doc to document a complex REST API and
my experience was almost complete the opposite for a number of reasons.

1.) Asciidoctor is powerful but exceedingly tedious to edit. It's especially
painful to use for documenting an API in advance--wikis like Confluence are
far easier to use and also allow commenting.

2.) Spring REST Doc generates snippets of asciidoc text that you must
laboriously incorporate into the parent asciidoc. It's particular painful when
combined with maven (another source of pain for some of us). Anybody who has
asked the question "where do I look in target to find my output?" as well as
"now that I found the output how do I make it go somewhere else instead?"
knows what I mean.

3.) The unit tests that Spring REST Doc depends on to generate output are hard
to maintain for anything beyond trivial cases. I've spent countless hours
debugging obscure bugs caused by Spring IoC problems. Also, the DSL format
used to define output of examples is hard to understand--just getting URLs to
show https schemes and paths takes time.

Finally, I would disagree that Swagger is purely designed to document existing
REST interfaces. We're using it to design the interfaces in advance. It's not
perfect but works better than other tools I have found let alone informal
specification via a wiki. Spring REST Doc is close to useless for design.

------
pibi
It looks like the perfect workaround is to use some middleware to autogenerate
the Swagger docs, at least to keep code and documentation in sync. After a
while I found myself doing the opposite, using Swagger to autoconfigure
endpoints ([https://github.com/krakenjs/swaggerize-
express](https://github.com/krakenjs/swaggerize-express)) and even mongodb
models ([https://github.com/pblabs/swaggering-
mongoose](https://github.com/pblabs/swaggering-mongoose)). Here is my actual
reference architecture: [https://github.com/pibi/swagger-rest-api-
server](https://github.com/pibi/swagger-rest-api-server)

Best thing about this approach is the clean separation between API definitions
and the implementation (all over the stack), so the teams can just discuss
about how to organize the resources and how to use them.

------
dqv
Here is a cached version as the site is currently giving me an HTTP 500:
[http://webcache.googleusercontent.com/search?q=cache:uQABqVC...](http://webcache.googleusercontent.com/search?q=cache:uQABqVCV2b0J:blog.novatec-
gmbh.de/the-problems-with-swagger/+&cd=1&hl=en&ct=clnk&gl=us)

------
maddening
To be honest I didn't knew that Swagger could generate API - still i wouldn't
use anything that generates code from some description (attempts I heard of
didn't worked out well in the past).

In projects I worked in Swagger was used to generate callable API from
existing implementation: add annotations (which are ugly :/, especially in
Scala, where such javaism hurts eyes even more), generate json, open it in
Swagger UI and let devs play with API.

What hurt me recently was 3.0 release - basePath got broken so, I got calls
generated with double slash (`host//api/call` etc.), and oauth2 is completely
broken and I cannot authenticate requests. 2.0 works with no issues, though I
find it sad that the vanilla version I downloaded uses hardcoded client_id and
client_secret.

------
Jdam
My problem with Swagger is the Swagger editor. It just works sometimes, but
sometimes everything is just red for no reason. Tried with Safari, ChrOme, Ff
on different Macs. Am I the only one who thinks this tool is unusable?

Edit: Cheers to you guys at Novatec, have to take a look on InspectIT again.

~~~
cookiecaper
It's definitely buggy. I've had more luck with it in Firefox than other
browsers. Refreshing and changing a line or two [usually] snaps it back into
shape.

Export your file frequently.

------
zip1234
I think Swagger is nice--codegen makes it simple to generate API clients for
various languages/frameworks. Saves a lot of time and potential sources of
errors. If there is something easier/better/more reliable, then I am all ears,
but Swagger keeps getting better.

------
tannhaeuser
Why are folks using Swagger or other tools for supposedly simple REST services
at all? It's not like Swagger is a "standard" or something, and from the
comments it appears using tooling for REST is a zero-sum game or even net
loss.

~~~
voycey
We started it using it for it's documentation and developer console generation
ability at first, I have to say that I am much happier when I get given a
swagger definition for an API, it lets me generate a client pretty much
instantly and as long as the definition is written well it more often than not
halves my integration time

~~~
tannhaeuser
I don't know if you're aware of the SOAP vs REST debate 10 years ago or Web
Services vs CORBA before that. Client generation, or any code generation at
all, was seen as a big no-no in the REST camp, so I find it ironic that today
this is used as Swagger et. al.'s saving grace. What I frequently see is that
inherently action-oriented protocols are crammed into resource-oriented REST
facades, only without any formal interface descriptions at all, and without
formal transactional or authorization semantics. OTOH, JSON REST services
can't be used without browser-side glue code at all so the Web mismatch
argument isn't working either. Makes you really wonder if there is any
rationality or progress in middleware usage at all.

------
glukki
Most of developers use Swagger wrong. But this is the right approach:
[https://github.com/swagger-api/swagger-node/](https://github.com/swagger-
api/swagger-node/)

Swagger is a contract. From contract you can generate documentation, client,
input/output data validation, mock responses, integration tests, and something
else, I'm sure.

If you start development from swagger — you can get everything in sync. That
way you can't forget to update documentation, validation rules, tests, or
whatever you generate from swagger. That way you can do work once! No work
multiplication!

It makes development So Much Easier!

------
epiecs
I also looked at swagger but found it needlessly complex for my needs. I opted
for blueprint api coupled with aglio to generate html docs and also provided a
nicely prepped postman collection including testing :)

------
tomelders
I think Koa (or Express) are the best tools for developing an API
spec/mock/doc that's useable and useful from the get go. You can have an
endpoint working in seconds, and it's easy to add all the different scenarios
you need. Dropping in middleware is easy too. And if you write your code well,
it's self documenting.

And ultimately, it's documentation for developers. I think it's as easy for a
non-js dev to parse and understand an endpoint controller than it is to parse
whatever freaky-deaky API documentation someone has cobbled together.

------
janslow
Whilst Swagger Codegen doesn't create perfect libraries and some of the
generators don't support all the features, once it's set up, it's just as easy
to create a client for every language as it is for just one.

For example, we create multiple client libraries, HTML documentation and a
partial server (so we don't have to manually write the parameter parsing and
models serializers).

Another advantage is you can start consuming the API as soon as the API design
is agreed, by using a generated mock server instead of waiting for the real
one to be implemented.

------
andreygrehov
In terms of API documentation, the biggest problem is making sure the
documentation is in sync with the actual code. I'm looking into using JSON
Schema [1] along with Swagger and Dredd [2]. Making it all language-agnostic
is a key. If anyone is doing anything similar, please, share your experience.

[1] [http://json-schema.org/](http://json-schema.org/)

[2]
[http://dredd.readthedocs.io/en/latest/](http://dredd.readthedocs.io/en/latest/)

~~~
abraae
We have hundreds of APIs, and we use RAML + json schema.

Since Swagger (OpenAPI) seems to be gaining ascendancy, I recently (some
months ago) looked at migrating off of RAML, but at that time the Swagger guys
had a philosophy that they would only support a subset of json schema.

I get their reasons - they want to be able to generate code. But the things
they didn't support (like oneOf - needed whenever you have a set of resources
of varying types) are a show stopper for many APIs with even moderately
complex payloads.

For us at least, its more important to have a single source of truth for our
APIs than to be able to generate code from the specs. Hence we remain on RAML
(which seems great - just looking like its losing the popularity contest).

~~~
vasusen
We also use RAML + json schema primarily as the single source of truth. We use
[https://jsonschema.net](https://jsonschema.net) to generate json schema by
providing it examples.

------
jerven
This is a bit off topic, but I feel that Swagger etc... and actually most API
docs are to human centric. You can't auto chain APIs together without a lot of
developer intervention. The one thing I saw that allowed that was SADI
services [1]. An awesomely pragmatic use of the semantic web. Pity it did not
get picked up by Google etc...

[1] [http://sadiframework.org/](http://sadiframework.org/)

------
andrewdb
I with there was a way to easily generate a swagger spec from a java project
as a build artifact out of the box, instead of having to serve the spec as a
dedicated API endpoint. There are some plugins, such as swagger-maven-plugin
[0], that do give you this functionality, though.

[0]: [https://github.com/kongchen/swagger-maven-
plugin](https://github.com/kongchen/swagger-maven-plugin)

------
akmanocha
Agreed with some and not all. In essence anythung can be abused. Seagger being
URI is well documented well argued problem. And no support for hypermedia too.
Asciidoc and Spring Rest Docs shine there.

But annotations is not IMHO. Swagger also doesny make thing more complex, they
already are. Swagger also doesnt amke reading docs difficult as such *apart
from URI problem above.

Also Spring Rest learnt from mistakes of Swagger so its a bit unfair on
swagger.

------
ssijak
Checkout Spring REST Docs [http://docs.spring.io/spring-
restdocs/docs/current/reference...](http://docs.spring.io/spring-
restdocs/docs/current/reference/html5/) . Always uptodate docummentation,
which double serves as tests, support HATOAS and more..

------
pushECX
For those that find it tedious to write swagger by hand, I've been using
Stoplight[1] at work and it's been working pretty well. You can create the
spec from scratch, or use their proxy to auto-document your api.

[1]: [https://stoplight.io/](https://stoplight.io/)

------
privacyfornow
I am working on auto generating clients with built in service subscription
based discovery, shock absorbers and circuit breakers based on open api
(swagger). We design our APIs with customer focus and therefore haven't run
into some of these problems so far.

------
a_imho
Problems with Swagger, it is really unfortunately named. I have never used
Swagger, to me it projects an aura that it is a quickly hacked weekend project
its authors did not put any effort to at least name properly. Yes, I know it
is irrational.

------
tschellenbach
Swagger is also a partial solution. I'd rather provide an API client library
and clearly document how to use the client library and not the underlying REST
API.

------
tootie
XSD is bulletproof. Why don't we just keep using XSD?

~~~
abraae
Because people don't want bullet proof. They want quick wins that work
straight away.

~~~
Mikhail_Edoshin
"For every complex problem there is an answer that is clear, simple, and
wrong." :)

------
tomc1985
One problem... it takes Swagger thirty-freakin-seconds to load its auto-
generated whatever for Magento Community, and it has to do this every freakin
time!

~~~
benmarks
That's... odd. Even running M2 off of DevBox on my Mac the swagger endpoint
renders in 5-10s (first visit).

------
kelnos
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.

~~~
Mikhail_Edoshin
JSON follows JavaScript syntax, which is specifically meant to be written
manually, i.e. by humans. (This is one of problems of JSON, by the way: look
at commas, for example, especially at the infamous problem of trailing commas
being illegal. This is definitely not meant to be written by machines.)

XML is indeed for machines, that is, the markup part of it. YAML may be more
readable, but note that the specification of YAML is about three times as
large as that of XML (and the XML specification also describes DTDs, a simple
grammar specification language). XML design goals are explicitly stated in its
specification, you're free to take a look.

~~~
gregopet
Any non-trivial format that's meant for humans MUST at the least allow
comments and should not force humans to write needless characters that would
be trivial for a machine to do without (e.g. quotes around key names). Also,
I'm flipping the bird to any format or language that doesn't allow me, a
human, to use multi-line strings. And in JSON I can't even at least
concatenate a few of them into a longer string. JSON is definitely not meant
to be written by humans.

------
mbesto
> The Problems with Swagger

> This is a Swagger misusage problem, not a problem from Swagger per sé.

The TL;DR is a list of gotchas and best practices the author has learned from
using Swagger.

~~~
MyMan1
Almost.

