This article will discuss two techniques that can be used to descriptions to your objects and fields in GraphQL when working with Apollo Server

Apollo Server makes use of the graphql-tools project to assist with schema building. It uses a simplified syntax to construct the object graph so that you do not need to deal with the complexity of working directly with GraphQLObjectType.

The definition for the object config looks like this:

type GraphQLObjectTypeConfig = {
  name: string;
  interfaces?: GraphQLInterfacesThunk | Array<GraphQLInterfaceType>;
  fields: GraphQLFieldConfigMapThunk | GraphQLFieldConfigMap;
  isTypeOf?: (value: any, info?: GraphQLResolveInfo) => boolean;
  description?: ?string
}

And the definition for a field config looks like this:

type GraphQLFieldConfig = {
  type: GraphQLOutputType;
  args?: GraphQLFieldConfigArgumentMap;
  resolve?: GraphQLFieldResolveFn;
  deprecationReason?: string;
  description?: ?string;
}

Both of these options include a description property. Typeically when working with graphql-tools we only provide a resolver:

const Person = {
  name: _ => _.name,
}

We can modify the fields to include descriptions a description by converting the resolver into an object that contains the resolve property and maps to our previous resolver. We can also add a description property that will be added to the GraphQL schema and will appear for the field in GraphiQL.

const Person = {
  name: { 
    description: 'This is a bar that goes with a foo',
    resolve: _ => _.name,
  }

Absent from this technique are the object descriptions. Fortunately, there is another way to add descriptions with graphql-tools.

The next technique is simpler and allows us to add descriptions to both fields and objects. This is simply by adding comments to the type definitions.

const typeDefs = `
  # Individual human
  type Person {
    # Name of the human
    name: String
  }

  # Root query
  type Query {
    # All of the people
    people: [Person]
  }
`;

From this you can use comments that start with # above objects, fields, or enums to provide a description.

For a working example, you can review the two techniques below: