Intro to GraphQL

[machikoyasuda]

• How to make your first viewer query:
• what is the URL
• how to get a token
• how to use graphiql to get the rest of the docs
• links to standalone graphql UI clients
• links to graphql learning resources
• links to API.docs.reactioncommerce.com to the Accounts/GraphQLResolvers namespace

[aldeed]

@machikoyasuda A few thoughts about GraphQL docs in general:

• We should definitely have a section with some intro content and "here's how to make your first viewer query" (what is the URL, how to get a token, links to standalone graphql UI clients, links to graphql learning resources)
• Beyond that, though, I don't think we should document the API/schema on docs.reactioncommerce. GraphQL schemas are self-documented by the comments, so viewing the docs within a graphql UI client is the best. I've been making sure we have good documentation for everything we add to the schema.
• We have been putting jsdoc on the resolver functions but they need to be organized somewhere in the API docs. I'm thinking maybe Accounts/GraphQLResolvers namespace, where the first part would be different depending on what the related namespace is. That way GraphQL docs for accounts resolvers will be sorted right after the other docs for accounts, which I think makes more sense than having everything lumped into a single GraphQL namespace. Thoughts?

[machikoyasuda]

@aldeed Thank you for your feedback!

• I made a ticket for your first bullet point.
• I agree with you on not mixing GraphQL schema docs into api.docs.
• I'll make a ticket in core for organizing namespaces for our current resolvers Accounts/GraphQLResolvers