4 ms·
Can you define "real proper documentation"?
by diveanon 6y ago
Can you define "real proper documentation"?
- capableweb 6y agoI'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.
- diveanon 6y agoI don't see how that is in any way specific to REST or GQL.
- capableweb 6y agoThe 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?
- diveanon 6y agoBecause 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.