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

21–30 of 163 posts

Re: Problems with Swagger

#21

Post by gamache »

richardwhiuk wrote: post #16
Yhippa wrote: post #10

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.

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.

A few counterpoints as I drift by:

The HAL hypermedia format is in use at Comcast, powering the Xfinity TV API. Not only does it take advantage of hypermedia and HATEOAS, it also splits requests/responses in order to make the most use of HTTP caches. https://boston2016.apistrat.com/speakers/ben-greenberg

Dunno if you're serious about not seeing how one could write a HATEOAS-driven client library or if I'm being trolled, but here's one that I wrote a couple of years ago: https://github.com/gamache/hyperresource There are many others as well (especially for the HAL format).

Re: Problems with Swagger

#22

Post by fsargent »

gkoberger wrote: post #2

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…

Check out Stoplight.io for a good tool for managing swagger documentation. It's a lot easier than managing the YAML itself.

Re: Problems with Swagger

#23

Post by cookiecaper »

xienze wrote: post #18
misterbowfinger wrote: post #11

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.

> A lot of Java developers are used to the SOAP APIs of yesteryear, Hmm way to paint Java developers as old dinosaurs... > and thus try to create clients with Swagger when they should be using gRPC or Thrift. They're trying to create clients with Swagger because they've made a REST API (yes you can do that in Java!). If you're using gRPC or Thrift, you're not making a REST API.

REST, if one insists on using it, should really be layered over top of something saner like gRPC or Thrift.

Personally, I've always found REST troublesome and overhyped. There's always a few incidents where you spend hours trying to figure out why something isn't working before realizing you had the wrong method on the request. There's no reason the thing you actually want to do to a resource should be tucked away in some header that's not always easy to access or see, it's just asking for trouble.

Re: Problems with Swagger

#24

Post by xienze »

richardwhiuk wrote: post #16
Yhippa wrote: post #10

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.

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.

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

There's nothing complicated about a client that understands Hypermedia links. You start at the root, it'll give you a set of links to follow, and you recurse. Here's a browser that can take a HATEOAS-compatible API and will let you work your way through the API: http://dracoblue.github.io/hateoas-browser/

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

Correct. HATEOAS is a neat parlor trick: point a dumb client at your API and watch it enumerate all the possible operations. Wow! The problem is that APIs aren't consumed that way, they're consumed by humans who need to decide which API calls to make based on user actions in the application... so developers will resort to consulting documentation in order to piece together the correct calls in the correct order. That's not something you can encode through Hypermedia. At best you can just model the relations between calls, but not the "how" or "why" of everything.

Re: Problems with Swagger

#25

Post by cookiecaper »

mcescalante wrote: post #14
gkoberger wrote: post #2

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…

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

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

It's definitely going to be faster to just write it at first. Swagger, and everything like it, is an investment.

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

That's auto-generated code for you. Can't rival humans (yet), but that doesn't automatically mean it's not useful.

Compare hand-rolled ASM with compiler-rolled ASM for an example. Human-written ASM will often be much more compact and readable, sometimes even more performant, but then you have to write ASM instead of letting the compiler do it for you.

Re: Problems with Swagger

#26

Post by k__ »

gkoberger wrote: post #2

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…

Are there any good alternatives?

I used REST which forced me basically to dig deep into online documentation when I wrote a client, but was rather straight forward to implement a server with.

I used SOAP which forced me to write a giant WSDL file, but was rather nice to work with on the client side.

GraphQL seems to obliterate this problem with its auto discovery mechanisms, but I don't know too much about it.

Re: Problems with Swagger

#27

Post by metachris »

gkoberger wrote: post #2

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…

I've implemented Swagger with several APIs and agree that it's crazy complex and time-consuming to write Swagger files manually.

I believe the best use-case for Swagger is to develop the API (perhaps just defining the routes with payload and response, but without controllers), and then auto-generating the Swagger files. This way the API consumers always have an up-to-date documentation, and there is only one place which represents the current state of the API.

Re: Problems with Swagger

#28

Post by [deleted] »

gkoberger wrote: post #2

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…

[deleted]
Post reply on HN