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

61–70 of 163 posts

Re: Problems with Swagger

#61

Post by 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) and even mongodb models (https://github.com/pblabs/swaggering-mongoose). Here is my actual reference architecture: 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.

Re: Problems with Swagger

#62

Post by haikuginger »

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

Personally, I don't understand why codegen is even necessary as opposed to a pure object-oriented client that works directly from the Swagger spec. Before I knew Swagger existed, I actually implemented such a client based on my own made-up spec.[0] It's relatively naive, but I attribute that more to my relative youth in development than to the concept itself.

[0]https://github.com/haikuginger/beekeeper

Re: Problems with Swagger

#63

Post by soofaloofa »

cookiecaper wrote: post #23
xienze wrote: post #18

Earlier quoted context omitted.

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

I'm not even sure what you mean. RPC is fundamentally different than REST and I don't know how you can layer on over top of the other?

Re: Problems with Swagger

#64

Post by sebular »

cookiecaper wrote: post #50
djur wrote: post #32

Earlier quoted context omitted.

What HTTP servers and clients are you using that don't clearly log the request method? I've never seen one where it's easier to read the body of the request than the method.

How about urllib, the Python default? def handle_thing(thing): r = urllib.request.Request(url='example.com', data={'stuff': 1}) return urllib.request.urlopen(r) Just one example. I know the tooling has improved somewhat since REST has become extremely common, so this is less of an issue now than it used to be (for example, most people use the Python requests module now, which makes it harder to use the wrong method (…

You're going on about the value of "conventional methods" in a criticism of using HTTP verbs?

Understanding the difference between a GET and a POST isn't some new-fangled idea, it's decades old. Like Tim Berners Lee old.

I didn't even know what Thrift was until I Googled it, and found out it was developed at Facebook. Okay.

I'm stunned. Do you write code that runs on the internet? How did you even get employed?

Re: Problems with Swagger

#66

Post by carapace »

Touche wrote: post #51

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.

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

I mean the essential difference. ;-)

Re: Problems with Swagger

#67

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

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) and embed it in our Slate documentation using our Slate documentation generator. (https://github.com/buremba/swagger-slate)

Here is an example: http://api.rakam.io/

Re: Problems with Swagger

#68

Post by eropple »

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

- Most statically-typed languages are a pain in the ass when it comes to HTTP responses because those responses can't be reified without types, and returning JSON blobs that don't have mapping types on the other end super sucks. I can do it myself if I absolutely have to--but making me waste my time doing it is silly.

Re: Problems with Swagger

#69

Post by eropple »

pbreit wrote: post #46
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…

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.

Re: Problems with Swagger

#70

Post by cookiecaper »

sebular wrote: post #64
cookiecaper wrote: post #50

Earlier quoted context omitted.

How about urllib, the Python default? def handle_thing(thing): r = urllib.request.Request(url='example.com', data={'stuff': 1}) return urllib.request.urlopen(r) Just one example. I know the tooling has improved somewhat since REST has become extremely common, so this is less of an issue now than it used to be (for example, most people use the Python requests module now, which makes it harder to use the wrong method (…

You're going on about the value of "conventional methods" in a criticism of using HTTP verbs? Understanding the difference between a GET and a POST isn't some new-fangled idea, it's decades old. Like Tim Berners Lee old. I didn't even know what Thrift was until I Googled it, and found out it was developed at Facebook. Okay. I'm stunned. Do you write code that runs on the internet? How did you even get employed?

>You're going on about the value of "conventional methods" in a criticism of using HTTP verbs?

Yes? These have some intrinsic value that is defined in the domain. There is no potential of vocabulary contamination because everyone comes into the domain with a clean state. An ambiguous, abused common vernacular is worse than a clean domain-specific one.

>Understanding the difference between a GET and a POST isn't some new-fangled idea, it's decades old. Like Tim Berners Lee old.

GET and POST usually work out OK; it's stuff like HEAD, PUT, and PATCH that people usually argue about, not to mention response codes.

GET, POST, and the HTTP intricacies are fine as a concern for HTTP clients. REST has shot through that and made it something that everyone has to worry about.

The issue is not only that no one can agree on how to do REST, but it's also, as stated in my other comment, that REST makes it harder to see what's going on. It requires important information (the verb) to be tucked away into something that takes extra steps to access. I'm not saying it's impossible to access that; I'm just saying it's error prone to do it this way.

>I didn't even know what Thrift was until I Googled it, and found out it was developed at Facebook. Okay.

I hate most "Project-By-BigCo" projects, but not everything that comes out of Google or Facebook is automatically evil.

Thrift is now controlled by the Apache Foundation, not Facebook. And it's a very common IDL, but I'll refrain from returning your snark. ;)

>I'm stunned. Do you write code that runs on the internet?

I'm not the only one. [0]

>How did you even get employed?

Just lucky I guess.

[0] https://twitter.com/skamille/status/588713316358475776

Post reply on HN