docql

Generate static HTML documentation for GraphQL APIs.

Overview

GraphiQL is great. So are tools like Altair and Insomnia. But they aren't necessarily enough.

docql comes in when you want documentation for GraphQL APIs that lives in a shared place. Having HTML documentation allows teams to link to specific objects and fields to enhance conversation, reference the docs when away from the computer, and generally have a place to see the entire GraphQL schema at a glance.

Examples

• GitHub v4 API: generated
• GraphQL's example Star Wars API: generated

Use

There are two ways to use docql.

npx

The easiest way to get started is to run docql off of the npm registry.

npx docql -e $API -o ./doc

native binaries

If native binaries are more your style and you have access to Rust's cargo, you can install with cargo install.

cargo install docql
docql -e $API -o ./doc

Command line options

USAGE:
    docql [OPTIONS] --output <path> <--endpoint <url>|--schema <path>>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -e, --endpoint <url>        The URL of the GraphQL endpoint to document
    -x, --header <header>...    Additional headers when executing the GraphQL introspection query (e.g. `-x
                                "Authorization: Bearer abcdef"`
    -n, --name <name>           The name to give to the schema (used in the title of the page) [default: GraphQL Schema]
    -o, --output <path>         The directory to put the generated documentation
    -s, --schema <path>         The output of a GraphQL introspection query already stored locally