SpectaQL is a Node.js library that generates static documentation for a GraphQL schema using a variety of options:
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
Anvil provides easy APIs for all things paperwork.
Learn more on our Anvil developer page.
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:
:tada: This supporting blog post outlines our use-case and implementation, and may be worth a read :tada:
Using SpectaQL to generate your documentation has a number of benefits, such as:
<body> content is generated) so output can be integrated into your existing site.Install SpectaQL:
npm install -g spectaql
# OR
yarn global add spectaql
This is a global installation, but you can also either:
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/.
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.
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.
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.
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)
...
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:
addMetadata method from our Apollo Plugin under the hood, so please see the documentation there or this example file to understand its format.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.
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:
spectaqlDirective option in the config-example.yml file for information on how to enable and tweak this approach.options argument is a List/Array of Input Objects that have the following shape:{ key: String!, value: String! }
value fields should be provided as strings, and they will be appropriately parsed based on the supported value of the key field.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-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\"]" }])
}
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.
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.
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}})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.
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
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.
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.
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.
SpectaQL is licensed under the MIT License – see the LICENSE.md for specific details.
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!
Powered by Anvil
3.0.2
cheerio@1.0.0-rc.12
FAQs
A powerful library for autogenerating static GraphQL API documentation
We found that spectaql demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.