Hacker News Reader

Comment by knlam | Hacker News Reader

Compare to REST, GraphQL have many advantages. However, IMO the tooling is still not there yet (Especially the caching, batching/data loaders are PITA).

One of the biggest selling point rarely come up is that you get the API docs for free through the playground. No more Swagger bad API

View on HN

You might get reference documentation for free but you don't get real, proper documentation that actually teaches the user anything. So basically the biggest selling point (for you) for GraphQL is the same as biggest selling point for Swagger? The quality of those reference docs is more based on the developer writing them, rather than the technology who allows it.

Can you define "real proper documentation"?

I'm only contrasting it to reference documentation. So in the case of GraphQL, you get reference documentation that shows you exactly how it can be used. But it won't show you _why_ you'll use it, or _what_ it can be used for. It also doesn't show what invariants you're working with, or in what way the endpoints are otherwise restricted with.

Real proper documentation is not just a list of endpoints and their attributes but explanations of those as well as other things.

I don't see how that is in any way specific to REST or GQL.

The original comment said "One of the biggest selling point rarely come up is that you get the API docs for free" while comparing it to Swagger. Both GraphQL and Swagger gives the same ability to generate API reference documentation.

So how is that the "biggest selling point" of GraphQL when it's not even new in the ecosystem?

Because swagger docs are defined via proprietary yaml definitions whereas graphiql exposes a more useful interface that is actually derived from your code, which in most cases is automatically generated from your DB model.

I've written a lot of swagger docs over the years, GQL is a massive improvement.

Reply on news.ycombinator.com