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

151–160 of 163 posts

Re: Problems with Swagger

#151

Post by skyde »

cobookman wrote: post #71
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.

100% agree, if you can afford to use GRPC. It's much simpler than having to use swagger.

Re: Problems with Swagger

#152

Post by beders »

People often don't make a crucial distinction: Are you developing an API that happens to be accessible via HTTP or are you developing a Web Service.

For an API where you control both the server and the client, you don't need to use REST.

For a Web Service, where you don't control which clients are using, you are better off with a RESTful implementation supporting hypermedia. Especially if you are interested in keeping clients happy and not give them the middle-finger shaped like a incompatible-v2 version of your service.

Re: Problems with Swagger

#153

Post by beders »

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 called a browser.

Re: Problems with Swagger

#154

Post by ogrim »

eddieroger wrote: post #146
ogrim wrote: post #117

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…

> why should I when I can have it generated? Because maybe you work on a team where half are creating an API and half are creating a client, and if you write a Swagger spec first, you can both be working at the same time, against the same contract, and just meet in the middle? And if you're working on the consumer side of things, you can take that spec and stand it up against a mocking engine that will now give you s…

One can still do what you are describing and have the Swagger spec generated. On my platform, I would just specify data types and the interfaces, and have Swashbuckle parse this and spit out the Swagger spec. No need to hand-code Swagger while creating the contract up front. After this step, one could work at both sides of the contract independently as you describe.

Re: Problems with Swagger

#155

Post by glukki »

Most of developers use Swagger wrong. But this is the right approach: https://github.com/swagger-api/swagger-node/

Swagger is a contract. From contract you can generate documentation, client, input/output data validation, mock responses, integration tests, and something else, I'm sure.

If you start development from swagger — you can get everything in sync. That way you can't forget to update documentation, validation rules, tests, or whatever you generate from swagger. That way you can do work once! No work multiplication!

It makes development So Much Easier!

Re: Problems with Swagger

#156

Post by eleumik »

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…

in my opinion oneOf is bad for interoperability

Re: Problems with Swagger

#158

Post by Mikhail_Edoshin »

kelnos wrote: post #107

Oh, man. There is so much wrong with this article. Here we go: > The documents are written in YAML, which I call XML for lazy people No. That's ridiculous. XML (and JSON, for that matter) is designed to be read and written by machines, not humans. (If the design goal was actually primarily for humans to read and write it, the designers failed. Miserably.) YAML is a nice middle ground, in that it can be unambiguously…

JSON follows JavaScript syntax, which is specifically meant to be written manually, i.e. by humans. (This is one of problems of JSON, by the way: look at commas, for example, especially at the infamous problem of trailing commas being illegal. This is definitely not meant to be written by machines.)

XML is indeed for machines, that is, the markup part of it. YAML may be more readable, but note that the specification of YAML is about three times as large as that of XML (and the XML specification also describes DTDs, a simple grammar specification language). XML design goals are explicitly stated in its specification, you're free to take a look.

Re: Problems with Swagger

#160

Post by gregopet »

wing328hk wrote: post #132
mr_tristan wrote: post #38

I've found swagger codegen to be really, really inconsistent between different implementations. A few of them - I recall we had a team using Qt - didn't even generate compilable code. When I looked into the infrastructure of the codegen project, I found... mustache. Check it out yourself: https://github.com/swagger-api/swagger-codegen/tree/master/m... Mustache is fine for doing a little view rendering, but for langua…

> I've found swagger codegen to be really, really inconsistent between different implementations. A few of them - I recall we had a team using Qt - didn't even generate compilable code. When I looked into the infrastructure of the codegen project, I found... mustache. Yup, some generators (e.g. ActionScript, Qt5 C++) are less mature than the others (e.g. Ruby, PHP, C#). For the issues with Qt5 C++ generator, please o…

Mustache is the most limiting (not to mention ugly) template language I've seen in a long time. It allows no logic whatsoever and even writing simple if statements is tedious. We have a Swagger spec from which we generate Asciidoctor documentation via a Gradle plugin which works very nice, and generate basic POJOs for Java and POCOs for C#. That... does not work very well for our purposes.

We wanted to produce named enumerables by using custom extensions and found no way of doing it with Mustache. It didn't help that our custom extension YAML was passed into Mustache as serialized JSON. One of our developers took it upon himself to make it work and ended up writing his own simple version of the Codegen which works well enough for us. He tried modifying one of the backends preparing data for Mustache but then said rewriting it on his own was just simpler.

Post reply on HN