Rework examples to avoid using buildSchema

[danielrearden]

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 buildSchema to create a schema is very limiting, in that it prohibits declaring resolve and resolveType functions, 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 GraphQLSchema instance 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:

1. 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.

2. Show the schema created using graphql-tools' makeExecutableSchema. This would allow us to still use SDL while avoiding the pitfalls of using buildSchema. 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.

3. 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?

[IvanGoncharov]

@danielrearden I think it's a general problem with graphql-js docs.
I think all docs related to graphql-js shouldn't be part of this site and should live inside docs folder of graphql-js repo.
Since I don't have commit rights in this repo I can't do this migration or at least update docs in this repo.

AFAIK GraphQL Foundation took ownership of this repo and I tried to contact them but got no reply. But it looks like they finaly solve all legal issue so I will try again.

[danielrearden]

Ok, great. I guess we should table this until the docs are migrated then.

[dandv]

Any progress on this migration? I'm super confused by the ton of SO Q&Aa stating there's no type extension in GraphQL, at direct odds with the spec. At the same time, https://graphql.org/learn/schema/ mentions nothing about extend. What's going on? Is the https://graphql.org/learn documentation completely lacking anything about extending types?

[danielrearden]

@dandv I believe buildSchema/buildASTSchema currently does not support system type extensions, as per this open issue. If you need the functionality now, use graphql-tools.