diff --git a/docs/source/api/apollo-server.md b/docs/source/api/apollo-server.md index 0f06576b04c..9ff6bb013ed 100644 --- a/docs/source/api/apollo-server.md +++ b/docs/source/api/apollo-server.md @@ -19,23 +19,65 @@ The core of an Apollo Server implementation. For an example, see the [getting-st DocumentNode(s) generated by using [`gql`](#gql) tag. They are string representations of GraphQL schema in the Schema Definition Language (SDL). -```js -const typeDefs = gql` - type Author { - name - } -`; + ```js + const typeDefs = gql` + type Author { + name + } + `; -new ApolloServer({ - typeDefs, - resolvers, -}); -``` + new ApolloServer({ + typeDefs, + resolvers, + }); + ``` - * `resolvers`: <`Object`> _(required)_ + * `resolvers`: <`Object`> | <`Array`> _(required)_ A map of resolvers for the types defined in `typeDefs`. The key should be the type name and the value should be a `Function` to be executed for that type. + ```js + // Resolver map + const resolvers = { + Query: { + authors() { + return authors; + } + }, + }; + + new ApolloServer({ + typeDefs, + resolvers, + }); + ``` + + Multiple resolver maps may be passed as an `Array`: + + ```js + const authorResolvers = { + Query: { + authors() { + return authors; + } + }, + }; + + const bookResolvers = { + Query: { + books() { + return books; + } + }, + }; + + new ApolloServer({ + typeDefs, + // The resolver map objects are deeply merged + resolvers: [authorResolvers, bookResolvers], + }); + ``` + * `context`: <`Object`> | <`Function`> An object or function called with the current request that creates the context shared across all resolvers @@ -78,90 +120,90 @@ new ApolloServer({ A value or function called with the parsed `Document`, creating the root value passed to the graphql executor. The function is useful if you wish to provide a different root value based on the query operation type. -```js -new ApolloServer({ - typeDefs, - resolvers, - rootValue: (documentAST) => { - const op = getOperationAST(documentNode) - return op === 'mutation' ? mutationRoot : queryRoot; - } -}); -``` + ```js + new ApolloServer({ + typeDefs, + resolvers, + rootValue: (documentAST) => { + const op = getOperationAST(documentNode) + return op === 'mutation' ? mutationRoot : queryRoot; + } + }); + ``` -* `mocks`: <`Object`> | <`Boolean`> + * `mocks`: <`Object`> | <`Boolean`> - A boolean enabling the default mocks or object that contains definitions + A boolean enabling the default mocks or object that contains definitions -* `mockEntireSchema`: <`Boolean`> + * `mockEntireSchema`: <`Boolean`> - A boolean controlling whether existing resolvers are overridden by mocks. Defaults to true, meaning that all resolvers receive mocked values. + A boolean controlling whether existing resolvers are overridden by mocks. Defaults to true, meaning that all resolvers receive mocked values. -* `schemaDirectives`: <`Object`> + * `schemaDirectives`: <`Object`> - Contains definition of schema directives used in the `typeDefs` + Contains definition of schema directives used in the `typeDefs` -* `introspection`: <`Boolean`> + * `introspection`: <`Boolean`> - Enables and disables schema introspection. Disabled in production by default. + Enables and disables schema introspection. Disabled in production by default. -* `playground`: <`Boolean`> | <`Object`> + * `playground`: <`Boolean`> | <`Object`> - Enables and disables playground and allows configuration of GraphQL Playground. The options can be found on GraphQL Playground's [documentation](https://github.com/prismagraphql/graphql-playground/#usage) + Enables and disables playground and allows configuration of GraphQL Playground. The options can be found on GraphQL Playground's [documentation](https://github.com/prismagraphql/graphql-playground/#usage) -* `debug`: <`Boolean`> + * `debug`: <`Boolean`> - Enables and disables development mode helpers. Defaults to `true` + Enables and disables development mode helpers. Defaults to `true` -* `validationRules`: <`Object`> + * `validationRules`: <`Object`> - Schema validation rules + Schema validation rules -* `tracing`, `cacheControl`: <`Boolean`> + * `tracing`, `cacheControl`: <`Boolean`> - If set to `true`, adds tracing or cacheControl metadata to the GraphQL response. This is primarily intended for use with the deprecated Engine proxy. `cacheControl` can also be set to an object to specify arguments to the `apollo-cache-control` package, including `defaultMaxAge`, `calculateHttpHeaders`, and `stripFormattedExtensions`. + If set to `true`, adds tracing or cacheControl metadata to the GraphQL response. This is primarily intended for use with the deprecated Engine proxy. `cacheControl` can also be set to an object to specify arguments to the `apollo-cache-control` package, including `defaultMaxAge`, `calculateHttpHeaders`, and `stripFormattedExtensions`. -* `formatError`, `formatResponse`: <`Function`> + * `formatError`, `formatResponse`: <`Function`> - Functions to format the errors and response returned from the server, as well as the parameters to graphql execution(`runQuery`) + Functions to format the errors and response returned from the server, as well as the parameters to graphql execution(`runQuery`) -* `schema`: <`Object`> + * `schema`: <`Object`> - An executable GraphQL schema that will override the `typeDefs` and `resolvers` provided. If you are using [file uploads](https://www.apollographql.com/docs/guides/file-uploads.html), you will have to add the `Upload` scalar to the schema, as it is not automatically added in case of setting the `schema` manually. + An executable GraphQL schema that will override the `typeDefs` and `resolvers` provided. If you are using [file uploads](https://www.apollographql.com/docs/guides/file-uploads.html), you will have to add the `Upload` scalar to the schema, as it is not automatically added in case of setting the `schema` manually. -* `subscriptions`: <`Object`> | <`String`> | false + * `subscriptions`: <`Object`> | <`String`> | false - String defining the path for subscriptions or an Object to customize the subscriptions server. Set to false to disable subscriptions + String defining the path for subscriptions or an Object to customize the subscriptions server. Set to false to disable subscriptions - * `path`: <`String`> - * `keepAlive`: <`Number`> - * `onConnect`: <`Function`> - * `onDisconnect`: <`Function`> + * `path`: <`String`> + * `keepAlive`: <`Number`> + * `onConnect`: <`Function`> + * `onDisconnect`: <`Function`> -* `engine`: <`EngineReportingOptions`> | boolean + * `engine`: <`EngineReportingOptions`> | boolean - If the `APOLLO_KEY` environment variable is set, the Apollo Studio reporting agent starts automatically. The API key can also be provided as the `apiKey` field in an object passed as the `engine` field. See [EngineReportingOptions](#enginereportingoptions) for a full description of how to configure the reporting agent, including how to include variable values and HTTP headers. + If the `APOLLO_KEY` environment variable is set, the Apollo Studio reporting agent starts automatically. The API key can also be provided as the `apiKey` field in an object passed as the `engine` field. See [EngineReportingOptions](#enginereportingoptions) for a full description of how to configure the reporting agent, including how to include variable values and HTTP headers. -* `persistedQueries`: <`Object`> | false + * `persistedQueries`: <`Object`> | false - The persisted queries option can be set to an object containing a `cache` field, which will be used to store the mapping between hash and query string. + The persisted queries option can be set to an object containing a `cache` field, which will be used to store the mapping between hash and query string. -* `cors`: <`Object` | `boolean`> ([apollo-server](https://github.com/expressjs/cors#cors)) + * `cors`: <`Object` | `boolean`> ([apollo-server](https://github.com/expressjs/cors#cors)) - Pass the integration-specific CORS options. `false` removes the CORS middleware and `true` uses the defaults. This option is only available to `apollo-server`. For other server integrations, place `cors` inside of `applyMiddleware`. + Pass the integration-specific CORS options. `false` removes the CORS middleware and `true` uses the defaults. This option is only available to `apollo-server`. For other server integrations, place `cors` inside of `applyMiddleware`. -* `experimental_approximateDocumentStoreMiB`: `number` + * `experimental_approximateDocumentStoreSizeMiB`: `number` - > **This property is experimental.** It may be removed or change at any time, even within a patch release. + > **This property is experimental.** It may be removed or change at any time, even within a patch release. - When set, this sets the approximate size of the parsed/validated document - store (in MiB). This cache is used to save the already parsed and validated - `DocumentNode`s for re-use on subsequent queries which resolve to the same - `queryHash` (a SHA-256 of incoming operation). + When set, this sets the approximate size of the parsed/validated document + store (in MiB). This cache is used to save the already parsed and validated + `DocumentNode`s for re-use on subsequent queries which resolve to the same + `queryHash` (a SHA-256 of incoming operation). - When this property is omitted, the cache is still enabled with a default - size of 30MiB, which is generally sufficient unless the server is processing - a high number of unique operations. + When this property is omitted, the cache is still enabled with a default + size of 30MiB, which is generally sufficient unless the server is processing + a high number of unique operations. #### Returns @@ -271,7 +313,7 @@ The `makeExecutableSchema` method is re-exported from apollo-server as a conveni * `options` : <`Object`> * `typeDefs`: <`GraphQLSchema`> _(required)_ - * `resolvers` : <`Object`> + * `resolvers` : <`Object`> | <`Array`> * `logger` : <`Object`> * `allowUndefinedInResolve` = false * `resolverValidationOptions` = {}