Schema documentation in GraphQL - Mini Project: Build & Apply

Documenting a GraphQL Schema

📖 Scenario: You are building a simple GraphQL API for a bookstore. To help other developers understand your API, you need to add clear documentation to your GraphQL schema.

🎯 Goal: Create a GraphQL schema with types and fields that include descriptive documentation comments. This will help users understand what each part of the schema represents.

📋 What You'll Learn

Create a Book type with documented fields

Create a Query type with a documented field to fetch books

Use triple-quoted strings for documentation comments

Include descriptions for the schema, types, and fields

💡 Why This Matters

🌍 Real World

Documenting GraphQL schemas helps teams and API users understand the data and operations available, improving collaboration and reducing errors.

💼 Career

Many developer roles require writing clear API schemas and documentation, especially when working with GraphQL in frontend or backend development.

1

Create the Book type with documentation

Write a GraphQL type called Book with these documented fields: id (ID!), title (String!), and author (String!). Use triple-quoted strings to add the description "A book object" above the type and descriptions for each field as follows: "Unique identifier", "Title of the book", and "Author of the book".

GraphQL

"""A book object"""
type Book {
  # Add fields with documentation here
}

Hint

Use triple quotes """ before the type and each field to add descriptions.

2

Create the Query type with documentation

Add a Query type with a documented field called books that returns a list of Book objects. Use triple-quoted strings to add the description "Root query type" above the type and "List of all books" above the books field.

GraphQL

"""A book object"""
type Book {
  """Unique identifier"""
  id: ID!
  """Title of the book"""
  title: String!
  """Author of the book"""
  author: String!
}

"""Root query type"""
type Query {
  # Add the books field with documentation here
}

Hint

Remember to use triple quotes for the descriptions and define books as a list of non-null Book objects.

3

Add schema declaration with documentation

Add a schema declaration with a triple-quoted description "GraphQL schema for the bookstore". Set the query root type to Query.

GraphQL

"""A book object"""
type Book {
  """Unique identifier"""
  id: ID!
  """Title of the book"""
  title: String!
  """Author of the book"""
  author: String!
}

"""Root query type"""
type Query {
  """List of all books"""
  books: [Book!]!
}

# Add schema declaration with description here

Hint

The schema declaration sets the root query type. Use triple quotes above it for the description.

4

Complete the schema with all documentation

Ensure the entire GraphQL schema includes all documentation comments exactly as before: the schema description, the Book type with its fields and descriptions, and the Query type with the books field and its description.

GraphQL

"""A book object"""
type Book {
  """Unique identifier"""
  id: ID!
  """Title of the book"""
  title: String!
  """Author of the book"""
  author: String!
}

"""Root query type"""
type Query {
  """List of all books"""
  books: [Book!]!
}

"""GraphQL schema for the bookstore"""
schema {
  query: Query
}

# Review and confirm all documentation is present

Hint

Check that all descriptions and types are included exactly as specified.

Practice

1. What is the purpose of using triple quotes """ in GraphQL schema documentation?

easy

A. To define a new type in the schema

B. To write comments that are ignored by the server

C. To add descriptions to types and fields

D. To create a mutation operation

Solution

1. Step 1: Understand triple quotes usage in GraphQL

   Triple quotes """ are used to add descriptions to schema elements like types and fields.

2. Step 2: Differentiate from other schema elements

   They are not for defining types, comments, or mutations but for documentation purposes.

3. Final Answer:

   To add descriptions to types and fields -> Option C

4. Quick Check:

   Triple quotes = descriptions [OK]

Hint: Triple quotes always mean description text in GraphQL [OK]

Common Mistakes:

• Confusing triple quotes with comments
• Thinking triple quotes define types
• Using triple quotes for operations

2. Which of the following is the correct way to add a description to a GraphQL field named age?

easy

A. """User age""" age: Int

B. age: Int # User age

C. age: Int """User age"""

D. "User age" age: Int

Solution

1. Step 1: Identify correct syntax for field description

   In GraphQL, descriptions go before the field using triple quotes.

2. Step 2: Check each option

   """User age""" age: Int places """User age""" before age: Int, which is correct syntax.

3. Final Answer:

   """User age""" age: Int -> Option A

4. Quick Check:

   Description before field with triple quotes = correct [OK]

Hint: Put triple-quoted description right before the field [OK]

Common Mistakes:

• Placing description after the field
• Using single quotes instead of triple quotes
• Using comments (#) instead of descriptions

3. Given this schema snippet, what will the description of the name field be?

type Person {
  """Full name of the person"""
  name: String
  age: Int
}

medium

A. Full name of the person

B. Name of the person

C. No description

D. Person's age

Solution

1. Step 1: Locate the description for the name field

   The triple-quoted string """Full name of the person""" is right above name: String.

2. Step 2: Understand it applies as the description

   This means the description for the name field is exactly that string.

3. Final Answer:

   Full name of the person -> Option A

4. Quick Check:

   Description above field = "Full name of the person" [OK]

Hint: Description above field is the field's doc [OK]

Common Mistakes:

• Assuming no description if not inline
• Confusing field name with description
• Mixing descriptions of different fields

4. Identify the error in this schema documentation snippet:

type Query {
  """Fetch user by ID"""
  user(id: ID!): User
  """Fetch all users"""
  users: [User]
  "Fetch version info"
  version: String
}

medium

A. Descriptions must be after the field, not before

B. The description for version uses double quotes instead of triple quotes

C. Descriptions cannot be used on Query type fields

D. The id argument is missing a description

Solution

1. Step 1: Check description syntax for each field

   The first two fields use triple quotes correctly. The version field uses double quotes "Fetch version info", which is invalid.

2. Step 2: Confirm correct usage

   Descriptions must use triple quotes """ to be valid in GraphQL schema.

3. Final Answer:

   The description for version uses double quotes instead of triple quotes -> Option B

4. Quick Check:

   Descriptions need triple quotes, not double [OK]

Hint: Descriptions always need triple quotes, not double [OK]

Common Mistakes:

• Using single or double quotes instead of triple quotes
• Placing descriptions after fields
• Assuming arguments need descriptions

5. You want to document a GraphQL schema so that the Book type and its title field have clear descriptions. Which schema snippet correctly documents both?

hard

A. "A book in the library" type Book { title: String "Title of the book" }

B. type Book { title: String """Title of the book""" } """A book in the library"""

C. type Book { "A book in the library" title: String "Title of the book" }

D. """A book in the library""" type Book { """Title of the book""" title: String }

Solution

1. Step 1: Check how to document a type

   The type description must be placed immediately before the type keyword using triple quotes.

2. Step 2: Check how to document a field

   The field description must be placed immediately before the field definition using triple quotes.

3. Step 3: Validate each option

   Only """A book in the library""" type Book { """Title of the book""" title: String } correctly places triple-quoted descriptions before the type and field.

4. Final Answer:

   """A book in the library""" type Book { """Title of the book""" title: String } -> Option D

5. Quick Check:

   Descriptions before type and field with triple quotes = correct [OK]

Hint: Put triple-quoted descriptions right before type and field [OK]

Common Mistakes:

• Placing descriptions after types or fields
• Using single quotes instead of triple quotes
• Not adding description for both type and field