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

111–120 of 163 posts

Re: Problems with Swagger

#111

Post by emmelaich »

cookiecaper wrote: post #76
jessaustin wrote: post #39

Earlier quoted context omitted.

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

Perhaps REST as the thing you do over http with http verbs won't be around.

But the architectural principle called REST will be around forever because it's essentially the same thing as functional programming.

That REST is cache friendly corresponds exactly to the way that pure functions are memo-ising friendly.

Re: Problems with Swagger

#112

Post by badreaction »

We use swagger heavily and I can say the following: 1) We use the tolerant reader pattern. It is entirely possible to generate tolerant client code where the enum and adding new element does not cause issues. The problem here is not swagger but poor code gen.

2) We use hypermedia in all of our APIs extensively, I don't see how this is impacted by swagger? Hypermedia is a runtime discovery mechanism and so other than declaring the link structures in your schema, has no place in swagger. We don't use HAL, and wouldn't recommend it either.

Re: Problems with Swagger

#113

Post by badreaction »

We use swagger heavily and I can say the following: 1) We use the tolerant reader pattern. It is entirely possible to generate tolerant client code where the enum and adding new element does not cause issues. The problem here is not swagger but poor code gen.

2) We use hypermedia in all of our APIs extensively, I don't see how this is impacted by swagger? Hypermedia is a runtime discovery mechanism and so other than declaring the link structures in your schema, has no place in swagger. We don't use HAL, and wouldn't recommend it either.

Re: Problems with Swagger

#114

Post by tannhaeuser »

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.

Re: Problems with Swagger

#115

Post by voycey »

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

Re: Problems with Swagger

#116

Post by manmal »

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.

I was engaged in a smallish project recently where they used Swagger as a shared resource that synced server dev with mobile dev. It didn't work that well, as you can imagine.. I had to wait for the server folks to update/fix Swagger docs all the time. They also thought that they need not tell me when a breaking change occurred, because "you will see it in Swagger anyway". So I pulled changes regularly, and generated iOS code, and suddenly it broke, and then I had to hope that one of the server team is currently available for consultation.

Re: Problems with Swagger

#117

Post by ogrim »

I would never write Swagger by hand; why should I when I can have it generated? We are using Swashbuckle[0] to generate Swagger for our ASP.NET Web API, which have been a great experience. We can explore and test the API in Swagger UI. I have been sprinkling a bit of hypermedia on top of this with HAL, mainly just for having links. I have never met anyone wanting to go the full HATEOAS route, but simple links can go a long wa. Swagger UI have been great for this, as HAL alone isn't really expressive enough to document what a link means. On the consumer side, I have been using NSwag[1] to generate clients with good results.

[0] https://github.com/domaindrivendev/Swashbuckle [1] https://github.com/NSwag/NSwag

Re: Problems with Swagger

#119

Post by andrewdb »

I with there was a way to easily generate a swagger spec from a java project as a build artifact out of the box, instead of having to serve the spec as a dedicated API endpoint. There are some plugins, such as swagger-maven-plugin [0], that do give you this functionality, though.

[0]: https://github.com/kongchen/swagger-maven-plugin

Re: Problems with Swagger

#120

Post by vasusen »

beachy wrote: post #98
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…

We also use RAML + json schema primarily as the single source of truth. We use https://jsonschema.net to generate json schema by providing it examples.
Post reply on HN