Descriptions

GraphQL supports adding descriptions to types, fields, and arguments and more. These descriptions are used by tools like Graphiql and editor integrations to provide context to developers.

Grats makes it easy to populate these descriptions and keep them in sync with the implementaiton by using the leading free text in your docblocks as that construct's description.

Example

TypeScript

/** 
 * A registered user of the system.
 * @gqlType
 */
class User {
  /** 
   * A friendly greeting for the user, intended for 
   * their first visit.
   * @gqlField
   */
  hello(args: {
    /** The salutation to use */
    greeting: string;
  }): string {
    return `${args.greeting} World`;
  }
}

Playground

GraphQL

"""
 A registered user of the system.
"""
type User {
  """
    A friendly greeting for the user, intended for 
    their first visit.
  """
  hello(
    """The salutation to use"""
    greeting: String!
  ): String
}

Limitations

caution

In some cases, TypeScript does not support "attaching" docblock comments to certain constructs. In these cases, Grats is currently unable to extract descriptions.

For example, Grats is not currently able to attach descriptions to enum values defined using a type union.

/** @gqlEnum */
type GreetingStyle =
  /** For a business greeting */
  | "formal"
  /** For a friendly greeting */
  | "casual";

Playground

Will incorrectly extract this GraphQL:

enum GreetingStyle {
  formal
  casual
}