Problems with Swagger • Hacker News Board

Re: Problems with Swagger

#71

Post by cobookman » Tue, Apr 04, 2017, 9:54 PM UTC

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…

Have you looked at the protobuf grpc implementation. I find it way simpler than swagger. It also generates your server code as well.

Re: Problems with Swagger

#72

Post by cookiecaper » Tue, Apr 04, 2017, 9:58 PM UTC

soofaloofa wrote: post #63

cookiecaper wrote: post #23

Earlier quoted context omitted.

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?

RPC is not fundamentally different from REST. REST is a form of RPC. (/me ducks tomatoes thrown among boos and hisses from the crowd)

The difference is that the processes behind REST speak with HTTP. You're still doing a "remote procedure call"; you're asking for a remote process to execute some function on your behalf and return the result. RPCs facilitate the same exact thing. How is this a "fundamental" difference?

[I'm speaking here of the practical difference, not some difference that was originally hypothesized in the dissertation.]

Thrift contains both an RPC and an IDL, but they don't necessarily have to be used together. Protobufs is just an IDL; gRPC is the RPC, which was released just a year or two ago.

You would layer Thrift and REST by putting a REST API over the top of an interface defined in the Thrift IDL. You could also run the Thrift RPC for Thrift-compatible clients.

Re: Problems with Swagger

#73

Post by dandlift » Tue, Apr 04, 2017, 10:03 PM UTC

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

Re: Problems with Swagger

#74

Post by banachtarski » Tue, Apr 04, 2017, 10:05 PM UTC

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.

Re: Problems with Swagger

#75

Post by pushECX » Tue, Apr 04, 2017, 10:14 PM UTC

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/

Re: Problems with Swagger

#76

Post by cookiecaper » Tue, Apr 04, 2017, 10:15 PM UTC

jessaustin wrote: post #39

cookiecaper wrote: post #20

Earlier quoted context omitted.

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

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.

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.

Re: Problems with Swagger

#77

Post by janslow » Tue, Apr 04, 2017, 10:21 PM UTC

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.

Re: Problems with Swagger

#78

Post by cortesoft » Tue, Apr 04, 2017, 10:25 PM UTC

ajross wrote: post #56

querulous wrote: post #42

Earlier quoted context omitted.

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

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…

You obviously need SOME spec or schema to be able to understand what to do with hypermedia, but it really comes down to how many things you have to define. It lets you define a smaller number of pieces and their functionality, and then lets you compose those smaller pieces into larger functions, and even create new combinations after a client is created without having to update the client.

Re: Problems with Swagger

#79

Post by api » Tue, Apr 04, 2017, 10:26 PM UTC

API Blueprint is much, much cleaner: https://apiblueprint.org

Here's a renderer: https://github.com/danielgtaylor/aglio

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

Re: Problems with Swagger

#80

Post by cookiecaper » Tue, Apr 04, 2017, 10:26 PM UTC

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?

All the time? Most "RESTful" (meaningless term, by the way) APIs have a series of convoluted steps that are annoying and tedious to hand-roll.

Authentication is a good basic example. Different APIs will have different requirements for authentication headers. Successful authentication frequently requires multiple steps, like an initial request to get a session token. Many APIs will also require your request to be signed according to their specifications, and to stuff that signature in a header with a special name.

Every API expects to receive data in its own format. I don't want to have to make a bunch of validators that lay on top of your data model. These can and should be provided, and Swagger makes that automatic.

As eropple states, if something is making me do all of that by hand, I'm already looking for something else that will allow me to just say "import project_lib; project_lib.authenticate(); ..."

If you're just talking about something that is read-only and that only emits a single field I care about, sure, no need for a library. Something like the free version of ipinfo.io would be a good example.

Stuff that's more complicated than that, yes, it needs a client library.