Problems with Swagger • Hacker News Board

Re: Problems with Swagger

#121

Post by tdriggs » Wed, Apr 05, 2017, 6:29 AM UTC

w4tson wrote: post #54

richardwhiuk wrote: post #43

Earlier quoted context omitted.

I'm definitely not trolling - it's just that's not how clients work. I don't write a client by doing a random walk through the API until I get to the information I need, I want to call the API that I know I need to give me the information that I want, and for performance, I want it all to be returned on a single call ideally. e.g. If I want user B's playlist, I don't want to have to crawl: /friends/ => ['b': { 'links…

But it's not a random walk. And it sure beats custom apis returning random bags of data for any given UI screen. Sometimes you do a few more web calls than you might otherwise. If you can get away with it then great! Because the benefits are plenty Hell! Even just having the uri of where the resource came from is useful enough. That's before you've introduced related resources.

At this point aren't you still hard coding commands, but using "links" rather than URLs? And doesn't the dependency on every link in the chain outweigh one - easily maintained - URL?

Re: Problems with Swagger

#122

Post by daliwali » Wed, Apr 05, 2017, 6:30 AM UTC

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.

Re: Problems with Swagger

#123

Post by tannhaeuser » Wed, Apr 05, 2017, 6:30 AM UTC

voycey wrote: post #115

tannhaeuser wrote: post #114

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.

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

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.

Re: Problems with Swagger

#124

Post by cimi_ » Wed, Apr 05, 2017, 6:34 AM UTC

hjacobs wrote: post #41

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 * 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 (Python API-first) * follow be…

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

Re: Problems with Swagger

#125

Post by jshen » Wed, Apr 05, 2017, 6:35 AM UTC

daliwali wrote: post #122

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…

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

Re: Problems with Swagger

#126

Post by int_19h » Wed, Apr 05, 2017, 6:46 AM UTC

jayd16 wrote: post #100

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.

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.

Re: Problems with Swagger

#127

Post by icebraining » Wed, Apr 05, 2017, 7:01 AM UTC

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 has been extremely successful, having scaled to billions of services, like the one we're using right now.

"RESTful APIs" have mostly been a failure, I fully agree with you on that. The difference is that I think it's a cultural problem; when people like Licklider sensibly thought about a future wherein computers would learn to talk to each other (of which REST is a first step), as static protocols obviously didn't scale, we proved him wrong by sheer brute force. Watching something like Bret Victor's The Future of Programming, it's hard to miss the giant indictment of our whole profession.

That said, since I know the term is hopelessly lost, I don't push for REST either. Our service uses XML/JSON-RPC.

Re: Problems with Swagger

#128

Post by hodgesrm » Wed, Apr 05, 2017, 7:07 AM UTC

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

Re: Problems with Swagger

#129

Post by a_imho » Wed, Apr 05, 2017, 7:21 AM UTC

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.

Re: Problems with Swagger

#130

Post by Vinnl » Wed, Apr 05, 2017, 7:24 AM UTC

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?