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
}

Need a 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
}

Need a 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

Need a 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

Need a hint?

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