Home

Awesome

SpectaQL

npm downloads

<a href="https://www.useanvil.com/docs"><img src="/static/SpectaQL.png" width="800"></a>

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

  1. From a live endpoint using the introspection query.
  2. From a file containing an introspection query result.
  3. 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.

  1. PDF filling API - fill out a PDF template with a web request and structured JSON data.
  2. PDF generation API - send markdown or HTML and Anvil will render it to a PDF.
  3. Etch e-sign with API - customizable, embeddable, e-signature platform with an API to control the signing process end-to-end.
  4. 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?

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.

:tada:  Anvil uses SpectaQL for our own docs, and you can see them here. :tada:<br> :tada:  This supporting blog post outlines our use-case and implementation, and may be worth a read :tada:

<img src="/static/anvil-api-screenshot.jpg" width="800">

Benefits

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

Features

Getting Started

  1. 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.

  2. Define a config.yml that specifies how you'd like to generate your docs. See YAML Options for more.

  3. 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:

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

  1. 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.
  2. 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.
  3. 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 Introspection 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:

{ key: String!, value: String! }

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:

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 overlaid 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:

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:

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!

<a href="https://www.useanvil.com"><img src="/static/anvil.png" height="15"></a>  Powered by Anvil