I am working on auto generating clients with built in service subscription based discovery, shock absorbers and circuit breakers based on open api (swagger). We design our APIs with customer focus and therefore haven't run into some of these problems so far.
Problems with Swagger
31–40 of 163 posts
Re: Problems with Swagger
#32Earlier 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…
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.
Re: Problems with Swagger
#33My 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 use swagger annotations to generate a swagger json automatically from my REST services. It is quite effortless once set up.
Re: Problems with Swagger
#34In 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.
Re: Problems with Swagger
#35I'm surprised RAML isn't suggested as na alternative. http://raml.org/
Does it address the issues in the post?
The RAML 1.0 type system can help: http://adrobisch.github.io/blog/articles/hateoas-with-raml-1...
Re: Problems with Swagger
#36My 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…
Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]).
Re: Problems with Swagger
#37My 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…
> 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 you think you don't.
> the code it generated was frustrating, lengthy, and much more complex than the simple endpoints that I quickly wrote from scratch
Sure--but you didn't have to write it.
Re: Problems with Swagger
#38I'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 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.
I ended up just not using swagger-codegen, and created my own StringTemplate based system, which got the job done a lot faster. The swagger core model was really janky to build logic around, however, so this system was really implementation specific.
In the end, were I to do it all over again, I would have probably just built a different mechanism. And honestly, building your own damn little DSL and code generators for your use case will probably be faster then integrating Swagger. Especially if you do not use the JVM as part of your existing toolchain.
I've not found anything to support multiple languages easily. If I were to do something today, I'd probably create a custom API DSL, custom code generators, with an output for asciidoctor (which is awesome) and example and test projects that test the generated code. Once you get the pipeline going the work is pretty straightforward.
Re: Problems with Swagger
#39This seems more like, "issues with how Swagger is used in Java". A lot of Java developers are used to the SOAP APIs of yesteryear, and thus try to create clients with Swagger when they should be using gRPC or Thrift. In other language paradigms, I haven't faced this issue. Swagger is _just_ documentation, and a nice front-end on top. The Java annotations definitely make it easy to generate, though, I'll give it that.
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.
Re: Problems with Swagger
#40I 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'll be honest, I stopped reading the article as soon as it mentioned Hypermedia, because I instantly saw the problem as the author being upset that Swagger is not Hypermedia.
I have a really hard time seeing APIs ever reaching that level of standardization, and I'm tired of having the Hypermedia discussion. I generally support logically organized APIs with good documentation. As long as those things are true, I'm happy for the API.