Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the ApolloServer resolvers argument documentation #4426

Closed
wants to merge 4 commits into from
Closed

Update the ApolloServer resolvers argument documentation #4426

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3a88fc1
Update the ApolloServer resolvers argument docs
mdawar Jul 29, 2020
5375db5
Fix the ApolloServer parameters list indentation
mdawar Jul 29, 2020
54a78f1
Update makeExecutableSchema resolvers accepted types
mdawar Jul 29, 2020
1a7d002
Merge branch 'main' into patch-1
mdawar Aug 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 106 additions & 64 deletions docs/source/api/apollo-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<Object>`> _(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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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<Object>`>
* `logger` : <`Object`>
* `allowUndefinedInResolve` = false
* `resolverValidationOptions` = {}
Expand Down