I also looked at swagger but found it needlessly complex for my needs. I opted for blueprint api coupled with aglio to generate html docs and also provided a nicely prepped postman collection including testing :)
Problems with Swagger
141–150 of 163 posts
Re: Problems with Swagger
#142Earlier quoted context omitted.
But it's not a random walk. And it sure beats custom apis returning random bags of data for any given UI screen. Sometimes you do a few more web calls than you might otherwise. If you can get away with it then great! Because the benefits are plenty Hell! Even just having the uri of where the resource came from is useful enough. That's before you've introduced related resources.
At this point aren't you still hard coding commands, but using "links" rather than URLs? And doesn't the dependency on every link in the chain outweigh one - easily maintained - URL?
You're hard-coding 'terms' from a hypermedia 'vocab'.
The thing is, if you use well-known terms, your client will work against ANY API that uses those terms, not just the one that you coded it to work against.
Not only that, but the APIs will have flexibility to move things around, or delegate functionality to other hosts by linking through.
As for the cost of walking the chain, once a target resource has been found the can be cached, and you only need to rewalk if the resource 404/410s.
Re: Problems with Swagger
#143Earlier quoted context omitted.
every web browser you use is a hateoas client you get some html with embedded links and then the browser automatically goes and fetches css, js, images... the remaining links it just presents to you, the user, to follow or not as you choose hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or thrift. it's something else
The browser is driven by advanced AI wetware that understands the semantics of the data and can make decisions on what to do next. I think REST/HATEOAS purists have always overplayed the browser example. Pure machine to machine interaction is hard to automate.
You can use game AI techniques like needs-based-AI to create smart, resilient clients. What fun!
Re: Problems with Swagger
#144Earlier quoted context omitted.
> 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. There's nothing complicated about a client that understands Hypermedia links. You start at the root, it'll give you a set of links to follow, and you recurse. Here's a browser that can take a HATEOAS-compatible API and will let you work your way through the API: http://dracoblue.github.io/h…
I meant a user friendly client, not something aimed at API developers. Sure you can create something which is aimed at Developers, but it's not presenting the data in a way any user would understand, or in a way that a UX expert can flex. Fundamentally, your display logic should not be linked to your API schema, but HATEOAS essentially enforces that, because you can't predict what links will be available.
> I meant a user friendly client, not something aimed at API developers. Sure you can create something which is aimed at Developers
Just for clarity, are you talking about API Developers or API Client Developers? I would see the primary beneficiaries of HATEOAS being developers consuming your API - i.e. client developers.
Re: Problems with Swagger
#145My 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]). [0] https://github.com/metosin/compojure-api [1] https://github.com/metosin/ring-swagger
I do and have, yes. We generally push for design-first specs, which means there's nothing in place to generate the Swagger file yet. If the API is simple, as they should be, then it's not that awful, really.
Re: Problems with Swagger
#146I 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 something to test against while your API team finishes their work? Just because you would rather generate Swagger doesn't mean there's not a reason to write it by hand before writing code.
Re: Problems with Swagger
#147XSD is bulletproof. Why don't we just keep using XSD?
maybe b/c it's for XML and not JSON, which most REST apis use.
If you don't use namespaces, you can validate JSON against an XSD. When I'm doing a REST API in Spring, I'll use and XSD and XJC (XSD Java Compiler) to generate model classes. The API endpoints are able to process those models as XML or JSON with 1 line of config.
Re: Problems with Swagger
#148Re: Problems with Swagger
#149Re: Problems with Swagger
#150Agreed with some and not all.
In essence anythung can be abused.
Seagger being URI is well documented well argued problem. And no support for hypermedia too. Asciidoc and Spring Rest Docs shine there.
But annotations is not IMHO. Swagger also doesny make thing more complex, they already are. Swagger also doesnt amke reading docs difficult as such *apart from URI problem above.
Also Spring Rest learnt from mistakes of Swagger so its a bit unfair on swagger.