How to Document GraphQL API: Best Practices and Examples

To document a GraphQL API, add descriptive comments directly in the schema using triple quotes """ above types, fields, and arguments. Use tools like GraphQL Playground or GraphiQL to display these descriptions interactively for developers.

Syntax

GraphQL schema documentation uses triple quotes """ to add descriptions above types, fields, and arguments. These descriptions appear in API tools and help developers understand the API.

• Type description: Place above the type definition.
• Field description: Place above the field inside the type.
• Argument description: Place above the argument inside the field.

graphql

"""A user in the system"""
type User {
  """Unique ID of the user"""
  id: ID!
  """User's full name"""
  name: String!
  """User's email address"""
  email: String!
  """Fetch posts created by the user"""
  posts(limit: Int): [Post]
}

Example

This example shows a simple GraphQL schema with descriptions for a User type and its fields. These descriptions help API users understand what each part means.

graphql

"""A user in the system"""
type User {
  """Unique ID of the user"""
  id: ID!
  """User's full name"""
  name: String!
  """User's email address"""
  email: String!
  """Fetch posts created by the user"""
  posts(limit: Int): [Post]
}

"""A blog post"""
type Post {
  """Unique ID of the post"""
  id: ID!
  """Title of the post"""
  title: String!
  """Content body of the post"""
  content: String!
}

Common Pitfalls

Common mistakes when documenting GraphQL APIs include:

• Using single-line comments (#) which are ignored by many tools and do not appear in documentation.
• Not adding descriptions to arguments, which can confuse API users about their purpose.
• Writing vague or missing descriptions, reducing the usefulness of the documentation.

Always use triple quotes """ for descriptions and be clear and concise.

graphql

type Query {
  # This comment will NOT appear in docs
  user(id: ID!): User
}

# Correct way:
"""Fetch a user by their unique ID"""
type Query {
  """Get user by ID"""
  user(
    """Unique identifier of the user"""
    id: ID!
  ): User
}

Quick Reference

Tips for documenting GraphQL APIs effectively:

• Use """ triple quotes for all descriptions.
• Document types, fields, and arguments clearly.
• Keep descriptions short but informative.
• Use tools like GraphQL Playground or GraphiQL to view and test documentation.
• Update documentation as your schema evolves.

Key Takeaways

Use triple quotes """ to add descriptions in your GraphQL schema.

Document types, fields, and arguments for clear API understanding.

Avoid single-line comments as they do not appear in documentation tools.

Leverage GraphQL tools like Playground or GraphiQL to display docs interactively.

Keep documentation updated with schema changes for accuracy.