This is a sample/demonstration project for the graphql-docs gem (GitHub).

This project provides a complete, working example of a GraphQL API built with graphql-ruby and Sinatra, specifically designed to showcase how easy it is to integrate and use the graphql-docs gem to automatically generate beautiful, comprehensive documentation for your GraphQL APIs.

graphql-docs gem: RubyGems | GitHub

This is a sample project. It demonstrates best practices for integrating graphql-docs into a Ruby GraphQL application.

graphql-docs is a Ruby gem that automatically generates beautiful, static HTML documentation from your GraphQL schema. It creates searchable, navigable documentation for all your types, queries, mutations, and fields - no manual documentation writing required!

# Clone and install
git clone <this-repo>
cd graphql-docs-demo
bundle install

# Generate documentation
bundle exec rake docs

# View the documentation
open docs/index.html  # macOS
xdg-open docs/index.html  # Linux

That's it! You now have comprehensive, searchable documentation for the entire GraphQL API.

This demo shows everything you need to integrate graphql-docs into your own project:

• ✅ Complete working GraphQL API with queries and mutations
• ✅ Full graphql-docs integration (see Rakefile:40-54)
• ✅ Generated documentation examples in the docs/ directory
• ✅ Best practices for schema design and documentation
• ✅ Production-ready setup with tests and linting

This demo implements a Books API with classic literature:

Types:

• Book - Classic book with title, author, slug, description, genre, pages, and read count

Queries:

• books - Get all books
• book(slug:) - Get a specific book by slug

Mutations:

• markAsRead(slug:) - Mark a book as read (increments read count)

This demo shows the Ruby API approach (using GraphQLDocs.build in a Rake task), but graphql-docs also supports:

• CLI approach - Use the graphql-docs command with a dumped .graphql schema file
• Direct Ruby integration - Call GraphQLDocs.build from anywhere in your code

Add to your Gemfile:

From RubyGems (stable):

gem "graphql-docs", "~> 5.0"

From GitHub (latest, as used in this demo):

gem "graphql-docs", github: "brettchalupa/graphql-docs", branch: "main"

Then run:

bundle install

Note: This demo uses the GitHub main branch to showcase the latest features.

Add to your Rakefile (or create one):

desc "Generate GraphQL documentation using graphql-docs"
task :docs do
  require_relative "schema"  # Load your schema file
  require "graphql-docs"

  GraphQLDocs.build(
    schema: BooksSchema,      # Replace with your schema class
    output_dir: "./docs",     # Where to generate docs
    delete_output: true,      # Clean before generating
    base_url: "/docs"         # Base URL for links
  )

  puts "Documentation generated in ./docs"
end

That's the entire integration! See it in action in this repo at Rakefile:40-54.

Run the task:

bundle exec rake docs

Open docs/index.html in your browser directly, or:

Option 1: Use this demo's Sinatra app (already configured!)

bundle exec rake serve
# Visit http://localhost:4567/docs/

Option 2: Serve with Ruby's built-in HTTP server

ruby -run -e httpd docs -p 8000
# Visit http://localhost:8000

The gem creates a complete documentation site with:

• Schema overview - Complete API reference at docs/index.html
• Object types - Detailed pages for each type (e.g., docs/object/book/index.html)
• Queries - Documentation for all query operations
• Mutations - Documentation for all mutations
• Scalars, Enums, Interfaces - Complete type system documentation
• Search functionality - Find types and fields quickly
• Navigation sidebar - Easy browsing between types

For our Books API, graphql-docs generates:

docs/
├── index.html              # Schema overview
├── object/
│   └── book/
│       └── index.html      # Book type documentation
├── query/
│   ├── books/
│   │   └── index.html      # books query
│   └── book/
│       └── index.html      # book(slug:) query
├── mutation/
│   └── markasread/
│       └── index.html      # markAsRead mutation
├── scalar/
│   ├── string/
│   ├── int/
│   └── ...
└── assets/                 # CSS, JS, images
    └── ...

The GraphQLDocs.build method accepts many options for customization:

GraphQLDocs.build(
  schema: YourSchema,           # Required: Your GraphQL::Schema class
  output_dir: "./docs",         # Where to output files
  delete_output: true,          # Clean output dir first
  base_url: "/docs"             # Base URL for links
)

GraphQLDocs.build(
  schema: YourSchema,
  output_dir: "./docs",

  # Custom landing page content
  landing_pages: {
    index: File.read("./docs_templates/index.md")
  },

  # Custom templates for styling
  templates: {
    default: "./docs_templates/default.erb"
  },

  # Customize which types to document
  only: [:object, :query, :mutation],

  # Exclude specific types
  except: [:__Directive, :__Schema]
)

See the graphql-docs documentation for all available options.

If you prefer not to use the Ruby API, you can use the CLI with a dumped schema:

1. Dump your schema to a file:

This demo includes a schema:dump task:

bundle exec rake schema:dump

Or do it manually:

ruby -e "require_relative 'schema'; puts BooksSchema.to_definition" > schema.graphql

2. Generate docs with the CLI:

bundle exec graphql-docs schema.graphql --output docs

This is useful for CI/CD pipelines or when you don't want to load your entire application just to generate docs.

1. Add descriptions - Use the description: parameter on fields, types, and arguments in your schema
2. Document deprecations - Use deprecation_reason: for deprecated fields
3. Group related types - Use consistent naming conventions
4. Keep it updated - Regenerate docs after schema changes (add to CI/CD)

Example with good descriptions:

field :book, BookType, null: true, description: "Fetch a single book by its unique slug identifier" do
  argument :slug, String, required: true, description: "The URL-friendly slug for the book (e.g., 'pride-and-prejudice')"
end

This project is configured for deployment to Fly.io using the included Dockerfile whenever code is pushed to GitHub.

The Dockerfile will automatically:

1. Build the container image
2. Install dependencies (including git for GitHub gem sources)
3. Generate the GraphQL documentation during build
4. Deploy to Fly.io

Fly.io configuration:

• fly.toml - App configuration (region, VM size, port, etc.)
• Dockerfile - Container build instructions
• Procfile - Process configuration (optional, Dockerfile CMD is used)

The generated docs in docs/ are static HTML, so you can also:

• Commit to repo - Version with your code
• Deploy to GitHub Pages - Free hosting for public repos
• Upload to S3/CDN - Fast global delivery
• Serve from your app - Integrate with your Rails/Sinatra app

Just start the server and visit http://localhost:4567/docs/

• Ruby 3.0 or higher
• Bundler

git clone <this-repo>
cd graphql-docs-demo
bundle install

Start the GraphQL API server:

bundle exec rake serve
# or: bundle exec ruby app.rb

Then visit:

• http://localhost:4567 - Interactive GraphQL playground
• http://localhost:4567/docs/ - Generated API documentation (after running rake docs)

Get all books:

query {
  books {
    title
    author
    slug
    readCount
  }
}

Get a specific book:

query {
  book(slug: "pride-and-prejudice") {
    title
    author
    publishedYear
    description
    genre
    pages
    readCount
  }
}

Mark a book as read:

mutation {
  markAsRead(slug: "1984") {
    title
    author
    readCount
  }
}

curl -X POST http://localhost:4567/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ books { title author } }"}'

This project includes a production-ready Dockerfile for deployment to Fly.io or any container platform. You can also use it for local development.

With Docker:

docker build -t graphql-docs-demo .

With Podman:

podman build -t graphql-docs-demo .

The build process automatically:

1. Installs git and dependencies (required for GitHub gem sources)
2. Installs Ruby gems including graphql-docs from GitHub
3. Runs bundle exec rake docs to generate documentation
4. Creates an optimized production image

With Docker:

# Run in foreground
docker run --rm -p 8080:8080 graphql-docs-demo

# Run in background
docker run -d -p 8080:8080 --name graphql-docs graphql-docs-demo

# Stop background container
docker stop graphql-docs

With Podman:

# Run in foreground
podman run --rm -p 8080:8080 graphql-docs-demo

# Run in background
podman run -d -p 8080:8080 --name graphql-docs graphql-docs-demo

# Stop background container
podman stop graphql-docs

Then visit:

• http://localhost:8080 - Interactive GraphQL playground
• http://localhost:8080/docs/ - Generated API documentation
• http://localhost:8080/graphql - GraphQL API endpoint

Test the GraphQL endpoint:

curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ books { title author } }"}'

Test the docs are accessible:

curl http://localhost:8080/docs/

Check that docs were generated during build:

# With Docker
docker run --rm graphql-docs-demo ls -la /app/docs

# With Podman
podman run --rm graphql-docs-demo ls -la /app/docs

Open a shell in the container:

# With Docker
docker run --rm -it graphql-docs-demo /bin/bash

# With Podman
podman run --rm -it graphql-docs-demo /bin/bash

# Run tests and linter (default task)
bundle exec rake

# Run tests only
bundle exec rake test

# Run linter only
bundle exec rake lint

# Auto-fix linting issues
bundle exec rake lint_fix

# Start the server
bundle exec rake serve

# Dump GraphQL schema to schema.graphql file
bundle exec rake schema:dump

# Generate GraphQL documentation (the main point!)
bundle exec rake docs

This project uses StandardRB for Ruby style enforcement.

This project includes a GitHub Actions workflow (.github/workflows/ci.yml) that runs on every push and pull request:

• ✅ Runs all tests
• ✅ Runs StandardRB linter
• ✅ Dumps GraphQL schema
• ✅ Generates documentation
• ✅ Uploads artifacts (schema + docs)

This ensures the graphql-docs integration stays working and demonstrates a complete CI/CD setup.

Comprehensive test suite with Minitest (Ruby stdlib) and Rack::Test:

bundle exec rake test

• 11 tests, 78 assertions
• Tests queries, mutations, read counts, docs serving, and error handling

.
├── app.rb                   # Sinatra app with GraphQL endpoint + playground
├── schema.rb                # GraphQL schema (types, queries, mutations)
├── config.ru                # Rack config for Puma (required for containerized deployment)
├── data/books.yml           # Books database (YAML)
├── test/graphql_test.rb     # Test suite
├── Rakefile                 # Rake tasks including 'docs' task ⭐
├── Gemfile                  # Dependencies including graphql-docs gem ⭐
├── docs/                    # Generated documentation (run 'rake docs') ⭐
├── Dockerfile               # Container image for deployment
├── fly.toml                 # Fly.io deployment configuration
├── Procfile                 # Process configuration for Fly.io
└── README.md                # You are here!

Files marked with ⭐ are the key integration points for graphql-docs.

• graphql-docs GitHub Repository
• graphql-ruby Documentation
• GraphQL Specification

This project is licensed under the MIT License - see the LICENSE file for details.

This is a demonstration project. Feel free to fork and modify for your own learning purposes!

The entire purpose of this project is to demonstrate how easy it is to add comprehensive documentation to your GraphQL API using graphql-docs. Just add the gem, create a rake task, and run it!

Try it now:

bundle exec rake docs
open docs/index.html