graphql-docs turns a GraphQL schema into a documentation site in Ruby

Two ways to serve the same generated documentation

GraphQLDocs is a Ruby library and CLI for generating documentation from a GraphQL schema, and it offers two ways to serve the result.

The first is the Static Site Generator, which pre-generates all HTML files, and that is the default. The second is a Rack application that serves the documentation dynamically on demand.

That split is the central design decision of the project, and the README includes a comparison table that makes the trade explicit. Setup complexity is low for the static generator and medium for the Rack app. The first page load is instant for static and fast with caching for the Rack app. Schema updates are a manual rebuild on the static side and automatic or a reload on the Rack side. Hosting is any static host for the generator, while the Rack app requires a Ruby server. Memory usage is minimal for static and higher because pages are cached. Authentication is a separate layer for the static output and built-in middleware for the Rack app.

The best-for line says it plainly: public documentation and open source for the static generator, internal tools and dynamic schemas for the Rack app. That is a sensible split, since a docs site that changes on every deploy and a docs site behind your company login have genuinely different requirements.

The library takes a file, a string or a schema object

Used as a library, GraphQLDocs.build accepts three kinds of input, and the README presents them as the difference between less and more control.

# pass in a filename
GraphQLDocs.build(filename: filename)

# or pass in a string
GraphQLDocs.build(schema: contents)

# or a schema class
schema = GraphQL::Schema.define do
  query query_type
end
GraphQLDocs.build(schema: schema)

The three forms are worth distinguishing. A filename is read through GraphQL::Client, while a string is simply read. A schema class, in this case defined with GraphQL::Schema.define, is the case where you hand over a live schema object rather than a document, which is what you want in a Rails application where the schema is assembled in code.

The CLI is the simplified path, and it installs with the gem:

graphql-docs schema.graphql

That writes the output into the output directory. The full option list is available with graphql-docs -h, and the README notes that using it as a library is what gives you access to every supported option, which is the usual arrangement for a gem that has both a library and a command line front end.

The generation pipeline, phase by phase

The README describes the internals, and the description is unusually concrete for a documentation tool.

There are several phases going on inside the single GraphQLDocs.build call. The GraphQL IDL file is read, if you passed a filename, through GraphQL::Client, or simply read if you passed a string through schema. GraphQL::Parser then manipulates the IDL into a slightly saner format. GraphQL::Generator takes that saner format and begins applying items to the HTML templates. GraphQL::Renderer technically runs as part of the generation phase, passing the contents of each page and converting it into HTML.

Four stages, and the ordering matters. The parse step normalises the document, the generator walks it and fills the templates, and the renderer produces the final HTML. The README notes that you could break these calls up individually, which is a hint that the phases are usable on their own, and that matters if you want to post-process the output or drive the templates yourself.

The naming is worth noting for anyone reading the source. The classes are named after the role they play in the pipeline rather than after the concept, so GraphQL::Parser is not a generic GraphQL parser but this tool's parsing step.

The Rake task, and how arguments beat environment variables

For Rails applications and other Rake based projects, GraphQLDocs ships a Rake task so the documentation can be generated as part of the build. The recommended form is task arguments:

rake graphql-docs:generate[schema.graphql]
rake graphql-docs:generate[schema.graphql,./docs]
rake graphql-docs:generate[schema.graphql,./docs,/api-docs,true]

The environment variable form is the alternative, with GRAPHQL_SCHEMA_FILE=schema.graphql rake graphql-docs:generate, and the README states the precedence rule plainly: task arguments take precedence over environment variables.

The four arguments are passed in order, and they are the same four settings the environment variables carry. The schema file path is required. The output directory defaults to ./output/. The base URL for assets and links defaults to an empty string, and it is the setting that makes the difference between docs served from the root of a domain and docs served under a path. And delete_output, which defaults to false, controls whether the output directory is removed before generating.

The Rails integration example is the part most people copy. You enhance the asset precompile task so it depends on the docs task, and set the schema path with an environment variable:

# Rakefile or lib/tasks/docs.rake
Rake::Task["assets:precompile"].enhance(["graphql-docs:generate"])

The README also shows a custom task variant that invokes the task directly with the four positional values, which is how you point the output at public/api-docs with a base URL of /api-docs and delete the directory first.

The Rack app, and how it keeps a schema fresh

The Rack application exists for cases where a static build is the wrong answer. The README lists them: internal tools with frequently changing schemas, integration with existing Rails or Sinatra applications, adding authentication and authorization middleware, and dynamic schema loading from databases or APIs.

The requirement is the rack gem at version 2.x or 3.x, and the gem is compatible with both, so you use whichever your application requires. As a standalone application you write a config.ru:

require 'graphql-docs'

schema = File.read('schema.graphql')

app = GraphQLDocs::App.new(
  schema: schema,
  options: {
    base_url: '',
    use_default_styles: true,
    cache: true  # Enable page caching
  }
)

run app

and run it with rackup config.ru, then visit http://localhost:9292.

In Rails it mounts as a route, with mount GraphQLDocs::App.new(schema: MyGraphQLSchema) at /docs, and in Sinatra it is a map block alongside the rest of the application.

The dynamic features are the reason to pick this mode. Pages are generated when requested, generated pages are cached in memory and the caching is disabled with cache: false, and the schema can be reloaded without restarting the server:

app = GraphQLDocs::App.new(schema: schema)

# Later, reload with new schema
new_schema = File.read('updated_schema.graphql')
app.reload_schema!(new_schema)

Assets are served automatically, and missing types produce friendly error pages rather than a stack trace.

The project structure, and what a Ruby gem looks like here

The repository is a conventional Ruby gem layout. There is a graphql-docs.gemspec, a Gemfile, a Rakefile, a lib directory for the library code, exe for the executable, bin for the binaries, test for the tests, and a config.ru at the root, which is the standalone Rack example that the README shows.

The docs are published on RubyGems, with the gem page as the homepage, and the API documentation is on rubydoc.info, pointed at the main branch. The README shows both as key links, and the Ruby documentation link is the more useful of the two for anyone extending the tool.

The release history is v6.0.0 on 2026-01-22, v5.2.0 on 2025-02-10 and v5.1.0 on 2024-12-10, and the last push to the repository was on 2026-10-10 with the repository not archived. The presence of a major version bump in January 2026 is worth checking against your own version, because a 6.0 release is where breaking changes to the options or the generated output tend to land.

The repository also has a CHANGELOG.md, a CODE_OF_CONDUCT.md, a CONTRIBUTING.md, a .yardopts file for the documentation generator, and a .github directory. The topics list includes good-first-issue, which is a signal that the project wants contributions from people new to it.

Where graphql-docs is the wrong choice

The first limit is that the documentation is entirely derived from the schema. There is no place to write a paragraph explaining a business concept, a tutorial or a migration note. If your API needs prose, this produces the reference and you write the rest somewhere else, which is a normal arrangement but worth knowing before you adopt it.

The second is the input. The schema has to be available as a file, a string or a schema object, and it has to be a schema that can be parsed. A project whose schema is assembled at runtime from something the parser cannot read will need to export it first.

The third is the theme. The output is generated HTML, and while the README mentions a use_default_styles option and a base URL for assets, the project is not a theming system. If you need the documentation to look like the rest of your site, that is custom work on top of the generated output, and the README does not document a template override API.

The fourth is the hosting decision. The Rack app needs a Ruby server in production, which is a real operational commitment for what is, at heart, a documentation site, and the static generator exists precisely to avoid it. The comparison table makes that trade visible, and for most public documentation the static route is the right side of it.

The fifth is the version drift risk on a 6.0 release, and the general point that this is a gem you will depend on through Bundler, so the release cadence of the gem and your own update policy have to be reconciled.

Editorial conclusion

graphql-docs fits a Ruby team that wants schema documentation generated from the schema itself rather than kept in a wiki, and the two delivery modes cover the two common cases, a static site you can host anywhere for public API docs, and a Rack app for internal tools with a schema that changes often. It is the wrong tool if your documentation needs prose, since the output is derived entirely from the schema, and the wrong tool if you want a hosted service rather than a gem you run yourself. Before you adopt it, check three things: that your schema is available as a file, a string or a schema object, since those are the three input forms, that you decide which mode you want early, because the static and Rack paths have different hosting and authentication consequences, and that you check the major version, since the current release is 6.0.0 while the Rake task documentation covers argument and environment variable forms that differ in precedence. The code is MIT licensed, the current release is v6.0.0 from 2026-01-22, and the last push was on 2026-10-10.

Frequently asked questions

Official sources

1. brettchalupa/graphql-docs on GitHub
2. License: MIT
3. Project website
4. README
5. Releases