SpectaQL - generate static docs for a GraphQL schema

It's finally time to take a look at another useful library, this time we’ll check out SpectaQL, a Node.js library for generating static GraphQL API documentation. On GitHub its described as

A nice enhancement of DociQL

so before we get to SpectaQL and its features let’s take a look at what DociQL is.

The foundation

DociQL as the name suggests also deals with documentation. To be precise it fetches the schema from a GraphQL endpoint by using the introspection query and generates static documentation from it. It's supposed to help you save time and look good and it does just that, by using a well-known layout. It's also very flexible so you can easily customize it and create your own layout that looks exactly like you want.

Looking at SpectaQL it's easy to see they wanted to take that approach and build on it. The first noticeable difference is that it has more options to generate documentation from:

• a live GraphQL endpoint via the introspection query (so just like DociQL)
• a file containing an introspection query result
• a file with the schema definition in SDL

Features

That’s not all and SpectaQL provides you with a bunch of features. Out of the box it gives you the same three column layout mentioned previously and it's also easily customizable. There’s quite a few more customization options though, DociQL only has some basic CLI configuration options, SpectaQL also lets you modify the CSS. Additionally you’re not limited to just what's in the introspection query or the schema, via examples you can include static metadata about your schema or you can use the custom generator plugin to dynamically generate examples for fields and arguments.

For a clearer picture let’s sum up the features:

• it's completely free (MIT license)
• can generate documentation from three types of sources (endpoint, file with an introspection query result or file with a schema definition)
• additional support for examples from static metadata or the dynamic example generator
• blacklisting for areas or single elements (for example you can tell it to hide all mutations)
• customizable styles by modifying the CSS
• markdown support
• live preview

Source: github.com/anvilco/spectaql

You can have it both ways

In short, SpectaQL has quite a few additional features while still giving you the neat looking one-page three-column documentation out of the box and without any hassle. It's easily customizable by design and the devs openly advocate forking it if you have some additional ideas on how to improve it or make it do something differently. So if you’re looking for a basic solution for getting documentation for your GraphQL API or if you want to get creative in terms of how you want it to look, SpectaQL has got you cover