@stigg/spectaql
Advanced tools
A powerful library for autogenerating static GraphQL API documentation
Migrating from pre 1.0?
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.
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 lots 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.
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 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 2 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.
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.
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 | Types].<Query, Mutation, 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 master 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 run 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
FAQs
A powerful library for autogenerating static GraphQL API documentation
We found that @stigg/spectaql demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 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
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."