11–20 of 163 posts
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.
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…
Completely agree. This was one of the reasons I liked using hapijs and joi in the past; they combine to validate and setup your HTTP endpoints and the swagger documentation is literarily generated from that code and not some separate thing you have to write. Unfortunately, outside of that very specific space, very little seems to exist.
Hapijs has its own issues and it's rarely my goto node framework anymore but it's hard to beat doing documentation that way.
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 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.
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 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.
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.
My problem with Swagger is the Swagger editor. It just works sometimes, but sometimes everything is just red for no reason. Tried with Safari, ChrOme, Ff on different Macs. Am I the only one who thinks this tool is unusable? Edit: Cheers to you guys at Novatec, have to take a look on InspectIT again.
Export your file frequently.
This 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.
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.
This 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.
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 get a two-way ("streaming") connection in the RPC, and when this is discussed, they usually kibosh it pretty quickly by saying it's an unsupported case and that you can find some hacks online, but they don't want to talk about it any further.
This may not have been a big problem for them before gRPC was released for protobufs, but it's definitely something that's worthy of attention and response now. I know lots of people who are going with protobufs instead because of this.
The other thing is that while Thrift boasts a lot of language compatibility, several of these are buggy.