Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Problems with Swagger

blog.novatec-gmbh.de

Post reply on HN
Print view View original

91–100 of 163 posts

Re: Problems with Swagger

#91

Post by pbreit »

eropple wrote: post #69
pbreit wrote: post #46

Earlier quoted context omitted.

Is whatever value people are getting out of client libraries provided by something generic like http://unirest.io ? When does it make sense to issue API-specific client libraries for a plain ole RESTful API?

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

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

Re: Problems with Swagger

#92

Post by tomc1985 »

eropple wrote: post #68
tomc1985 wrote: post #47

Earlier quoted context omitted.

One could argue that clients can roll their own damn client implementations, and that autogenerating client libraries is the folly. This is just REST, no?

One could argue that, but one would be creating a really sucky developer experience that can be avoided with comparatively little work. - "Just REST" doesn't actually encapsulate meaningful behaviors by itself. It's by no means complete. Swagger is a partial patch on this by trying to reduce the scope of what your API is supposed to be doing, and it's not perfect, but it's better than "welp, throw Grape at it." - Mos…

> "Just REST" doesn't actually encapsulate meaningful behaviors by itself.

Yes it does: open a socket, speak HTTP, get some data back. Yeah you'll have to feed it into a JSON parser or whatever but apparently people consider that a lot of work now?

I do agree on the points with statically-typed languages. Finagling dynamic types in such a system is a PITA. But I do not see the need for autogenerating tooling if you're consuming REST from a dynamic language; all you've automated is the HTTP call and data parsing (which takes very little time to write oneself)

Maybe I've been living under a rock the past 10 years but REST has never required very much effort, either to implement or consume. Then out of nowhere I begin encountering all these weird-ass tools -- Swagger (and who the F named that one, Old Spice?), Grape, whatever. All this crazy software to do all these crazy things when... it's just HTTP and JSON over the wire :/

At some point people need to ask themselves, 'how much abstraction is too much abstraction?'

Swagger's real value-add to me is in a standard documentation format for REST APIs, but the last instance I used of Swagger made my work more difficult :/

Re: Problems with Swagger

#93

Post by empthought »

cookiecaper wrote: post #88
icebraining wrote: post #85

Earlier quoted context omitted.

RPC doesn't have an Uniform Interface. Say you have a user profile, which has a Gravatar associated. Sure you can have a getUserProfile() procedure that fetches the user information, but what about the image? You can write a getUserAvatar() procedure that proxies it, but that's wasteful. In a RESTful system, you have a Resource Identifier (URL) that you can indicate as an hypermedia reference (link), with which the c…

REST doesn't have a uniform interface in practice, either. I haven't read the dissertation so I can't really comment on the hypothetical REST (though it is on my reading list now, and not that it really stops anyone else), I can only comment on what, in the real world, passes for a "REST API". "REST" principles certainly sound nice on paper, but for the most part, it's clear that they're completely implausible to rea…

REST APIs must be hypertext-driven[1].

The term "REST," like so many others, now "means" something totally different than what the inventor of the term intended.

[1]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Re: Problems with Swagger

#95

Post by int_19h »

tomc1985 wrote: post #47
eropple wrote: post #37

Earlier quoted context omitted.

> 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…

One could argue that clients can roll their own damn client implementations, and that autogenerating client libraries is the folly. This is just REST, no?

One can argue that, but in practice, this often means that the clients will just take their business and go elsewhere.

Re: Problems with Swagger

#96

Post by 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.

Re: Problems with Swagger

#97

Post by dwaltrip »

gkoberger wrote: post #60
emidln wrote: post #36

Earlier quoted context omitted.

Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]). [0] https://github.com/metosin/compojure-api [1] https://github.com/metosin/ring-swagger

In my experience (we have a product where people upload Swagger files), most people write it by hand. There's two reasons: 1) Many people use Swagger to design (rather than document), meaning the Swagger comes before the code 2) Most people just prefer to write it out, since the tooling otherwise isn't necessarily great (especially for non-developers) We ran a poll and "by hand" (either on Swagger Hub/Apiary, or loca…

How does a non-developer know how to document or design an API?

Re: Problems with Swagger

#98

Post by beachy »

andreygrehov wrote: post #34

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/ [2] http://dredd.readthedocs.io/en/latest/

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

Re: Problems with Swagger

#100

Post by jayd16 »

int_19h wrote: post #96

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…

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.
Post reply on HN