docql

Generate static HTML documentation for GraphQL APIs.

Overview

GraphiQL is great. So are tools like Altair and Insomnia.

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][github v4 generated]
• GraphQL's example Star Wars API: [generated][swapi generated]

[github v4 generated]: [swapi 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, each release comes with native binaries on the GitHub release page.

docql -e $API -o ./doc

Or you can install your own from crates.io using Rust's cargo.

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

Command line options

USAGE:
    docql [OPTIONS] --endpoint <url> --output <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