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

131–140 of 163 posts

Re: Problems with Swagger

#131

Post by Meic »

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…

At the risk of linking to another tool which will only get you 80% of the way there...

OpenAPI-GUI [1] [2] is a visual editor / creator for OpenAPI / Swagger 2.0 definitions. It runs entirely client side in the browser.

It's certainly useful enough to start an OpenAPI definition by providing all the boilerplate. Later, as the definition increases in complexity you can cut-and-paste in the editor of your choice.

[1] https://mermade.github.io/openapi-gui [2] https://github.com/mermade/openapi-gui

Re: Problems with Swagger

#132

Post by wing328hk »

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 open an issue via http://github.com/swagger-api/swagger-codegen/issues/new so that the community can help work on it.

> Mustache is fine for doing a little view rendering, but for language generation... it's really obnoxious to use. Say you want to customize the output. Well, now you're basically replacing one of those magic .mustache files. And what's the model you use to generate those mustache files? Well, you got to look through the codebase for that.

Instead looking through the codebase, you may also want to try the debug flag (e.g. debugOperations, debugModels) to get a list of tags available in the mustache templates: https://github.com/swagger-api/swagger-codegen/wiki/FAQ#how-...

I agree that mustache may not be the best template system in the world but it's easy to learn and developers seem pretty comfortable using it.

> Especially if you do not use the JVM as part of your existing toolchain.

One can also use docker (https://github.com/swagger-api/swagger-codegen#docker) or https://generator.swagger.io (https://github.com/swagger-api/swagger-codegen#online-genera...) to leverage Swagger Codegen without installing JVM.

Thanks for the feedback and I hope the above helps.

(Disclosure: I'm a top contributor to the project)

Re: Problems with Swagger

#133

Post by wing328hk »

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.

For Swagger Codegen, you can also customize the mustache templates in whatever way you want (e.g. replacing 4-space with tab in C# client templates). The auto-generated code may sometimes look lengthy but we usually do it with reasons based on feedback from developers. Please share with us more via https://github.com/swagger-api/swagger-codegen/issues/new so that we can further improve the output.

You may find Swagger Codegen a huge time saver in use cases in which the endpoints are growing (e.g. from 20 endpoints in v1 to 40 endpoints in v2) and you will need to provide API clients in multiple langauges (e.g. Python, Ruby, PHP, C#, etc)

Disclosure: I'm a top contributor to Swagger Codegen

Re: Problems with Swagger

#134

Post by eropple »

pbreit wrote: post #91
eropple wrote: post #69

Earlier quoted context omitted.

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

I sort of thought the opposite, that the client libraries are what is getting in the way.

So you enjoy writing a bunch of boilerplate class files that are manual translations of somebody else's doc?

Re: Problems with Swagger

#135

Post by icebraining »

kelnos wrote: post #110
icebraining wrote: post #85

Earlier quoted context omitted.

RPC doesn't have an Uniform Interface. Say you have a user profile, which has a Gravatar associated. Sure you can have a getUserProfile() procedure that fetches the user information, but what about the image? You can write a getUserAvatar() procedure that proxies it, but that's wasteful. In a RESTful system, you have a Resource Identifier (URL) that you can indicate as an hypermedia reference (link), with which the c…

There is absolutely no reason why you can't implement the same REST concepts on top of another RPC mechanism.

Of course you can. But x86 machine code doesn't have Monads just because Haskelll can be compiled to it. In both cases, the concepts have to be broken up to be implemented, as they are not meaningful at that level.

Re: Problems with Swagger

#136

Post by czardoz »

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…

This is why we developed the Postman Collection format. It's very simple, and expressive. More importantly, it's a way to impose _less_ constraints on the API Designer, while also being richly documented.

Here's an example of a very simple collection: https://github.com/postmanlabs/postman-collection-transforme...

But, you can also go and have something like https://github.com/postmanlabs/postman-collection-transforme..., which is very well documented. The generated documentation for this is available too: https://docs.postman-echo.com

Disclaimer: I work at Postman.

Re: Problems with Swagger

#137

Post by tomelders »

I think Koa (or Express) are the best tools for developing an API spec/mock/doc that's useable and useful from the get go. You can have an endpoint working in seconds, and it's easy to add all the different scenarios you need. Dropping in middleware is easy too. And if you write your code well, it's self documenting.

And ultimately, it's documentation for developers. I think it's as easy for a non-js dev to parse and understand an endpoint controller than it is to parse whatever freaky-deaky API documentation someone has cobbled together.

Re: Problems with Swagger

#138

Post by godzilla82 »

icebraining wrote: post #135
kelnos wrote: post #110

Earlier quoted context omitted.

There is absolutely no reason why you can't implement the same REST concepts on top of another RPC mechanism.

Of course you can. But x86 machine code doesn't have Monads just because Haskelll can be compiled to it. In both cases, the concepts have to be broken up to be implemented, as they are not meaningful at that level.

Can you please explain. Which REST concept cannot be implemented? I think the problems that REST/SOAP solve,is that the "levels" that you speak about, have already been implemented by someone else. I am talking of serialization, transport level details (e.g. SOAP over JMS) etc. If even transport level abstraction has been taken care of by the implementers, then which concept do you think, cannot be implemented.

Re: Problems with Swagger

#139

Post by maddening »

To be honest I didn't knew that Swagger could generate API - still i wouldn't use anything that generates code from some description (attempts I heard of didn't worked out well in the past).

In projects I worked in Swagger was used to generate callable API from existing implementation: add annotations (which are ugly :/, especially in Scala, where such javaism hurts eyes even more), generate json, open it in Swagger UI and let devs play with API.

What hurt me recently was 3.0 release - basePath got broken so, I got calls generated with double slash (`host//api/call` etc.), and oauth2 is completely broken and I cannot authenticate requests. 2.0 works with no issues, though I find it sad that the vanilla version I downloaded uses hardcoded client_id and client_secret.

Re: Problems with Swagger

#140

Post by daenney »

badreaction wrote: post #112

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…

Totally agree on the codegen bits.

> To mitigate this problem just stop generating code and doing automatic deserialisation. Sadly, I have observed that’s a very hard habit to break.

That conclusion really irks me. In Java, if you're using AutoMatter for example, you're one annotation away from discarding unknown fields and many other serialisation frameworks offer the same ability. It's not a default (which imho it should be) but it's trivial to fix.

Post reply on HN