Merge pull request #5022 from apollographql/sb/custom-directive-edits

First batch of edits to custom directives article

Author: Stephen Barlow

docs/gatsby-config.js

@@ -75,7 +75,7 @@ module.exports = {
           ],
           Appendices: [
             'proxy-configuration',
-            'migration-two-dot',
+            'installing-graphql-tools',
             'migration-file-uploads',
             'migration-engine-plugins',
           ],

docs/source/api/graphql-tools.md

@@ -5,7 +5,7 @@ sidebar_title: graphql-tools
 
 The `graphql-tools` library enables the creation and manipulation of GraphQL schema. Apollo Server is able to accept a `schema` that has been enabled by `graphql-tools`. Apollo server directly exports all the function from `graphql-tools`, enabling a migration path for more complicated use cases.
 
-> Apollo Server uses `graphql-tools` version 4. For documentation of the _latest_ version of `graphql-tools`, see the [official `graphql-tools` documentation](https://www.graphql-tools.com/docs/introduction).
+> Apollo Server includes `graphql-tools` version 4. To use another version of the library, see [Using a different version of graphql-tools](../installing-graphql-tools/).
 
 ```js
 const { makeExecutableSchema } = require('apollo-server');

docs/source/installing-graphql-tools.md

@@ -0,0 +1,45 @@
+---
+title: Using a different version of graphql-tools
+---
+
+Apollo Server includes `graphql-tools` version 4 by default. If you want to use a newer version, you can do so with the following steps:
+
+1. Install `graphql-tools` separately in your project.
+
+2. Update your `ApolloServer` constructor to provide the `schema` option _instead of_ `typeDefs`, `resolvers`, and `schemaDirectives`. You instead pass these options to the `makeExecutableSchema` function, which you provide as the value of `schema`:
+
+    ```js:title=index.js
+    const { ApolloServer, gql } = require("apollo-server");
+    const { makeExecutableSchema } = require("@graphql-tools/schema");
+
+    const server = new ApolloServer({
+      schema: makeExecutableSchema({
+        typeDefs,
+        resolvers,
+        schemaDirectives: {
+          // ...directive subclasses...
+        }
+      }),
+      // ...other options...
+    });
+    ```
+
+3. Add the following definitions to your schema `typeDefs`:
+
+    ```graphql:title=schema.graphql
+    enum CacheControlScope {
+      PUBLIC
+      PRIVATE
+    }
+
+    directive @cacheControl(
+      maxAge: Int
+      scope: CacheControlScope
+    ) on FIELD_DEFINITION | OBJECT | INTERFACE
+
+    scalar Upload
+    ```
+
+    Apollo Server uses these types for its [caching](./performance/caching/) and [file upload](./data/file-uploads/) functionality. It usually defines these types automatically on startup, but it _doesn't_ if you provide the `schema` option to the `ApolloServer` constructor.
+
+For more information on the latest version of `graphql-tools`, see the [official documentation](https://www.graphql-tools.com/docs/introduction/).