Description
All of the examples in the GraphQL.js tutorial demonstrate creating a schema using buildSchema. Create a schema using SDL is simpler and less intimidating for beginners compared to initializing a GraphQLSchema instance directly. However, there's also a couple of undesirable consequences to this approach:
- Using
buildSchemato create a schema is very limiting, in that it prohibits declaringresolveandresolveTypefunctions, relying entirely on the default resolver logic. However beginners reading the tutorial may get the impression this is the preferred way to create a schema. - Showing adding functions root object (in order to get around not being able to actually declare resolvers) can lead to confusion around how to actually declare resolvers for fields and what parameters are passed to resolvers.
- Avoiding directly initializing the
GraphQLSchemainstance means the only examples of how to actually do that are buried in the documentation for the individual classes. It also means we can't show more advanced features like using Unions and Interfaces or creating custom scalars.
I can attest to the confusion created by the docs including the buildSchema function based on how many questions I end up answering on Stack Overflow about it. I think it would be worthwhile to update the docs to show constructing schemas using a more practical method. I would be happy to put up a PR for that if you would accept one, but there's a couple of different ways I think we could address the above concerns:
-
Show the schema created by using the GraphQLSchema class directly. This would help connect the tutorial with the rest of the GraphQL.js-specific documentation and provide additional usage examples. However, it might also introduce additional confusion since the implemention-agnostic parts of the docs describe the type system using SDL.
-
Show the schema created using
graphql-tools'makeExecutableSchema. This would allow us to still use SDL while avoiding the pitfalls of usingbuildSchema. The problem, of course, is that we would now be documenting use for a different library, even if it's one that's built on top of this one. -
Show both. We could show how to construct the same schema using both methods. It'd even be feasible to utilize a tabbed code block (like the ones used in docs like this and this) to allow users to switch back and forth between the two different approaches.
I think option 3 would be best, even if it will take some work. These changes would not only make the existing examples more helpful, but would also set the stage for us to expand the GraphQL.js docs into additional topics like abstract types, custom scalars, etc.
There's a related issue in the main repo (graphql/graphql-js#1368) but I figured I would ask on here since this is where the docs are still hosted. @leebyron @IvanGoncharov your thoughts?