spectaql

Autogenerate static GraphQL API documentation

1113

117

JavaScript

SpectaQL

SpectaQL is a Node.js library that generates static documentation for a GraphQL schema using a variety of options:

From a live endpoint using the introspection query.
From a file containing an introspection query result.
From a file, files or glob leading to the schema definitions in SDL.

The goal of SpectaQL is to help you keep your documentation complete, current and beautiful with the least amount of pain as possible.

Repository sponsored by Anvil

Horizontal Lockupblack
Horizontal Lockup copywhite

Anvil provides easy APIs for all things paperwork.

PDF filling API - fill out a PDF template with a web request and structured JSON data.
PDF generation API - send markdown or HTML and Anvil will render it to a PDF.
Etch e-sign with API - customizable, embeddable, e-signature platform with an API to control the signing process end-to-end.
Anvil Workflows (w/ API) - Webforms + PDF + e-sign with a powerful no-code builder. Easily collect structured data, generate PDFs, and request signatures.

Learn more on our Anvil developer page.

NOTICE

Migrating from pre 1.0?

Here are the breaking changes: BREAKING_CHANGES_1.md
Here’s a list of some of the interesting new changes: CHANGELOG.md

Out of the box, SpectaQL delivers a 3-column page with a modern look and feel. However, many aspects can be customized with ease, and just about everything can be customized if you’re willing to dig in.

SpectaQL also has a lot of advanced features and ways to enhance your GraphQL documentation.

🎉 Anvil uses SpectaQL for our own docs, and you can see them here. 🎉

🎉 This supporting blog post outlines our use-case and implementation, and may be worth a read 🎉

Benefits

Using SpectaQL to generate your documentation has a number of benefits, such as:

Your documentation will always be up-to-date
Your documentation will always be complete
Your documentation can be beautiful and “on brand”
Save developers time and headache by not having to write documentation

Features

Various ways to ingest your schema:
- Hit a live GraphQL endpoint with an introspection query
- Provide a file containing an introspection query result
- Provide a single SDL file containing your schema
- Provide an array of multiple SDL files to be merged into a final schema
- Provide a glob that leads to SDL files to be merged into a final schema
Will automatically generate documentation for all Types, Fields, Queries, Mutations, Arguments and Subscriptions by default.
Supports blacklisting entire areas (e.g. “don’t show Mutations”) and 1-off blacklisting.
Supports providing examples via static metadata, or dynamically via a custom generator plugin that you control.
Supports (beta) dynamic grouping and arranging of data via a custom data arrangment plugin that you control.
Supports light tweaking or complete customization of CSS, JS and HTML output via themes.
Supports markdown just about everywhere you can provide text.
Live preview mode while developing.
Many options for output:
- Specify a logo
- Specify a favicon
- Specify the target directory and HTML file name
- Can output JS and/or CSS “in line” in your HTML file, rather than as separate files.
- Can output in “embeddable” mode (only the <body> content is generated) so output can be integrated into your existing site.
- …and more!

Getting Started

Install SpectaQL:
```
npm install -g spectaql
# OR
yarn global add spectaql
```
This is a global installation, but you can also either:
- Clone this repository
- Add spectaql as a dependency to an existing project.
Define a config.yml that specifies how you’d like to generate your docs.
See YAML Options for more.
Generate your docs!
```
npx spectaql config.yml
```

Your generated documentation will be located in the public directory by default. You can either copy the generated HTML to your web server, write the output to somewhere else using the -t /path/to/ouputDir option, or add -D flag and view your docs live by pointing your browser to http://localhost:4400/.

Examples

The best way to figure out what SpectaQL can do is to clone this repository (or mimic the /examples directory) and play around with the example build and its data:

npm install
npm run develop ./examples/config.yml

That config will direct a build that flexes the most interesting parts of SpectaQL, so dig in a little and it should be a rewarding exercise.

YAML Options

To generate your documentation, SpectaQL requires a configuration YAML. This file is where you can specify most of the options to make your output the way you’d like it. All the supported options and their descriptions can be found in the config-example.yml file.

Environment variable substitution will be performed, so feel free to use environment variables in your config.

You can also see a minimal-ish working example YAML in the examples/config.yml file.

Command Line Options

Several options are supported via the CLI. Some are exclusive to the CLI, while others are also possible to specify in the YAML config. Options specified in the CLI take precedence over those that exist in the YAML config. All the supported options and their descriptions can be found in /src/cli.js.

Using SpectaQL as a Dependency

In addition to using SpectaQL as a global (or local) binary executable, it can also be used by your Node application as a dependency. More documentation will be coming soon but here is a quick example to get you started:

import { run } from 'spectaql'
...
const spectaqlOptions = {
   specFile: 'path/to/your/config.yml',
   resolveWithOutput: true,
}
const { html } = await run(spectaqlOptions)
...

Metadata

In our experience, nearly all of the stuff we need for the content of the documentation comes from things supported in GraphQL and introspection queries…but not everything. To supplement some things that are missing, SpectaQL provides support for including “metadata” about your schema that can be used when generating the output. The following options are currently supported:

example: When provided for a Scalar, Field or Argument, this value will be used as an “example” for the Field or Argument. It can be any value supported in JSON.
examples: Same as example, but allows an Array of examples to be provided, from which one random one will be used during generation.
undocumented: A Boolean value that can be provided on a Type, Field, Argument, Query or Mutation indicating that this item is not to be included in the resulting output. Useful for 1-off hiding of things where the default was to show them.
documented: Just like undocumented, except it will include it in the resulting output. Useful for 1-off showing of things where the default was to hide them.

SpectaQL supports 3 ways to include metadata to be used during processing:

Include your metadata in the introspection query (or introspection query results file). This requires manipulation of your introspection query results either on their way out from the server, or once in an output file. At Anvil, we use Apollo Server and leverage this plugin we wrote to “weave” our metadata into the introspection query results. This example output illustrates what an “interwoven” metadata scenario might look like.
Provide a standalone JSON file containing your metadata to be “woven” into your introspection query results by SpectaQL. SpectaQL uses the addMetadata method from our Apollo Plugin under the hood, so please see the documentation there or this example file to understand its format.
If you are providing your schema information via an SDL file or files, leverage the SpectaQL Directive feature to provide your metadata in your SDL through directives. See the SpectaQL Directive for more information.

NOTE: Another way to ensure that things are not documented is to pass your GraphQL Instrospection Results through Microfiber and perform the removal of any Types, Fields, Queries etc before they even reach SpectaQL. Just a thought.

The SpectaQL Directive

If you are providing your schema information via an SDL file or files, you can leverage the @spectaql directive and pass any of the supported metadata options to the options argument of that directive. This is a useful approach for those who are taking an “SDL-first” development approach. See the spectaqlDirective option in the config-example.yml file for more information on how to enable and implement this approach.

Here’s what you need to know:

See the spectaqlDirective option in the config-example.yml file for information on how to enable and tweak this approach.
The directive’s options argument is a List/Array of Input Objects that have the following shape:

{ key: String!, value: String! }

All the value fields should be provided as strings, and they will be appropriately parsed based on the supported value of the key field.
SpectaQL does not need you to add the definition of the spectaql directive, nor its SpectaQLOption input type to your SDL. They will be added (and removed) by SpectaQL automatically if you enable the feature. However, if you are using that same SDL to create an executable schema, you will need to add the directive and options definitions for your server to not complain.
The directive can be added to your SDL anywhere that directives are supported by GraphQL SDL syntax, but they may only have an impact on the areas that SpectaQL supports.

The directive-related SDL is:

directive @spectaql(options: [SpectaQLOption]) on QUERY | MUTATION | SUBSCRIPTION | FIELD | FRAGMENT_DEFINITION | FRAGMENT_SPREAD | INLINE_FRAGMENT | VARIABLE_DEFINITION | SCHEMA | SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
input SpectaQLOption { key: String!, value: String! }

Or you can generate the required directive SDL programmatically like so:

import { generateSpectaqlSdl } from 'spectaql'

const spectaqlSdl = generateSpectaqlSdl()
// Do something with this SDL

Once enabled, the directive can be used like so:

type MyType {
   "This field will be hidden, thanks to the options that were passed to the @spectaql directive"
   myField: String @spectaql(options: [{ key: "undocumented", value: "true" }])
   myFieldOtherField: String @spectaql(options: [{ key: "example", value: "An Example from the Directive" }])
   myFieldOtherOtherField: String @spectaql(options: [{ key: "examples", value: "[\"Example 1 from the Directive\", \"Example 2 from the Directive\"]" }])
}

Dynamic Example Generators

In addition to being able to use any static examples you’ve provided, SpectaQL also supports dynamically generating examples for Scalars, Fields and Arguments. When it comes time to generate an example, SpectaQL can pass all the necessary information about the Scalar, Field or Argument to your generator in order for it to decide what the example should look like. See the included example generator to see how it works.

NOTE: There is nothing wrong with this approach, and it may often times make the most sense. However, if you are thinking about going through the trouble of writing your own example generator methods, you might also consider taking that effort “upstream” and using it to add examples directly to your metadata before SpectaQL even gets involved. Just a thought.

Customizing CSS, JS, HTML, and Data Arrangement via Themes

SpectaQL supports a “theme” system that can be used to make minor tweaks to the default look, or to completely overhaul the output. This article should be really helpful to understanding how themes work and what they can do.

SpectaQL ships with 3 included themes that can be specified via the themeDir option:

default: Our default theme. This is the theme that will be used if do not specify any themeDir option.
basic: Outputs the same HTML structure as the default theme, but with minimal CSS styling.
spectaql: Outputs the same HTML structure as the default theme, but with some CSS enhancements.

In addition to those built-in themes, you can specify a path to a custom theme directory to the themeDir option. Your custom theme directory will be overlayed on top of the default theme directory, and therefore can include as much or as little overridden or additional files as necessary to obtain your desired output.

See /examples/themes/README.md for more information on how you can customize SpectaQL’s output with themes.

Reference Interpolation

All descriptions are rendered in a way that supports markdown. If you’d like to reference a Type, Query or Mutation SpectaQL supports some basic custom interpolation that will return links to the desired target. The format is as follows: {{[Queries | Mutations | Subscriptions | Types].<Query, Mutation, Subscription, or Type name>}}

Examples:

I'm a description with a simple reference to [String]({{Types.String}})
I'm a description with a cool looking reference to [`[String!]`]({{Types.String}})
I'm a description with a simple reference to [myQuery]({{Queries.myQuery}})

Custom Builds

The best option for customizing your output is to see if what you want to do is already supported out of the box:

There are various options in the CLI and YAML config for customizing your results.
Overriding CSS, JS and HTML is already supported via themes. Check themes README for more.
Overriding “examples” for things is already supported via metadata, or via a dynamic example generator.

If you need to change or extend SpectaQL beyond what’s supported out of the box, another option is to fork SpectaQL on GitHub and make your own modifications in the source. Forked repos are always public, so if you need changes to remain private you can consider doing a clone + mirror approach as outlined here. Either way, you can keep up-to-date by merging changes from the main branch.

Please consider submitting a Pull Request (or asking first via an Issue) for anything you think would be a useful addition to SpectaQL. We try to be pretty active about fixing and enhancing the project. Please also consider subscribing to the repo to keep up to date with the goings on.

Alternatively, you can just copy and modify the contents of app from the main repo and pass the path from your custom app path to the CLI using the -a flag.

Development

When developing, you’ll likely want to use the -D (or -d) development modes so that your output is hosted live for you, and changes to the code will trigger a rebuilding of the output:

npx spectaql -d path/to/config.yml

Testing

npm test
# OR
yarn test

The changes we made from the DociQL project are significant, and as a result there is only a limited amount of test coverage at this point. However, new code should be tested, and unit tests for the existing code will be added in the future…or are welcome as pull requests!

Testing is powered by Mocha/Chai and uses the BDD Lazy Var enhancement for writing RSpec-style tests.

Run npm test on the repository to start the automated tests.

Caveats

While it’s very robust, SpectaQL is still quite new and is evolving. It’s likely that there will be some bugs, breaking-changes, and other odd things until things harden up a bit more over usage and time. Please keep this in mind.

Contributors and Special Thanks

This library owes a very special thanks to the DociQL project, which served as a great starting point for SpectaQL to build on top of.

License

SpectaQL is licensed under the MIT License – see the LICENSE.md for specific details.

More Information

More info is available on the SpectaQL homepage.

You may also find this supporting blog post that outlines our use-case and implementation to be helpful.

All contributions are welcome.

Good luck and enjoy SpectaQL!