Static page generator for documenting GraphQL Schema
Install
npm install -g @graphidocs/docs
Use
Generate documentation from live endpoint
> graphidocs -e http://localhost:8080/graphql -o ./doc/schema
Generate documentation from IDL file
> graphidocs -s ./schema.graphql -o ./doc/schema
Generate documentation from for the "modularized schema" of graphql-tools
> graphidocs -s ./schema.js -o ./doc/schema
./schema.graphql
must be able to be interpreted with graphql-js/utilities#buildSchema
Generate documentation from json file
> graphidocs -s ./schema.json -o ./doc/schema
./schema.json
contains the result of GraphQL introspection query
Puts the options in your package.json
{
"name": "project",
"graphidocs": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
}
}
And execute
> graphidocs
Help
> graphidocs -h
Static page generator for documenting GraphQL Schema v1.0.4
Usage: node bin/graphidocs.ts [OPTIONS]
[OPTIONS]:
-c, --config Configuration file [./package.json].
-e, --endpoint Graphql http endpoint ["https://domain.com/graphql"].
-x, --header HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"].
-q, --query HTTP querystring for request (use with --endpoint) ["token=cb8795e7"].
-s, --schema, --schema-file Graphql Schema file ["./schema.json"].
-p, --plugin Use plugins [default=graphidocs/plugins/default].
-t, --template Use template [default=classic].
-o, --output Output directory.
-d, --data Inject custom data.
-b, --base-url Base url for templates.
-f, --force Delete outputDirectory if exists.
-v, --verbose Output more information.
-V, --version Show graphidocs version.
-h, --help Print this help
Plugin
In graphidocs a plugin is simply an object that controls the content that is displayed
on every page of your document.
This object should only implement the PluginInterface
.
Make a Plugin
To create your own plugin you should only create it as a plain object
or a constructor
and export it as default
If you export your plugin as a constructor, when going to be initialized,
will receive three parameters
schema
: The full the result of GraphQL instrospection queryprojectPackage
: The content of package.json
of current project (or the content of file defined with --config
flag).graphidocsPackag
: The content of package.json
of graphidocs.
For performance reasons all plugins receive the reference to the same object
and therefore should not modify them directly as it could affect the behavior
of other plugins (unless of course that is your intention)
Examples
export default class MyPlugin {
constructor(schema, projectPackage, graphidocsPackage){}
getAssets() { }
}
export default cost myPlugin = {
getAssets() { },
}
function MyPlugin(schema, projectPackage, graphidocsPackage) { }
MyPlugin.prototype.getAssets = function() { };
exports.default = MyPlugin;
exports.default = {
getAssets: function() { },
}
Use plugin
You can use the plugins in 2 ways.
Use plugins with command line
> graphidocs -p graphidocs/plugins/default \
-p some-dependencie/plugin \
-p ./lib/plugin/my-own-plugin \
-s ./schema.json -o ./doc/schema
Use plugins with package.json
{
"name": "project",
"graphidocs": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
"plugins": [
"graphidocs/plugins/default",
"some-dependencie/plugin",
"./lib/plugin/my-own-plugin"
]
}
}
Built-in plugin
TODO
Template
You can specify which template to use via the CLI:
> graphidocs -t classic \
-s ./schema.json -o ./doc/schema
Or via 'package.json':
{
"name": "project",
"graphidocs": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
"template": "classic"
}
}
The current built-in templates are:
Relative Path
The template can also take a relative path (from where command is executed):
> graphidocs -t ./my-template \
-s ./schema.json -o ./doc/schema
{
"name": "project",
"graphidocs": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
"template": "./my-template"
}
}
Node Module
To specify a node module as a template, specify the name as the template:
> graphidocs -t my-graphidocs-template \
-s ./schema.json -o ./doc/schema
{
"name": "project",
"graphidocs": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
"template": "my-graphidocs-template"
}
}
Create a Template
All rendering is done within the template. It's up to the template to pick what and how to render.
In order to render, you should extend the Template
class. There are a few methods
you must use:
getTemplateFiles
A way to get all the template files. Should return a promise of strings to the files.serialize
The method that will turn the data into text that will get written out.renderDirective
The method that will render the GraphQL directives.renderIndex
The method that will render the index file like index.html
.renderType
The method that will render the GraphQL types.
An example of this is (from the classic toolkit):
import * as glob from 'glob';
import { render } from 'mustache';
import { TypeRef } from '../../lib/interface';
import Template, { ITemplateFileMap } from '../../lib/Template';
import { getFilenameOf } from '../../lib/utility';
import { ITemplateData } from '../../lib/utility/template';
export default class ClassicTemplate extends Template {
public async getTemplateFiles(): Promise<string[]> {
return new Promise<string[]>((resolve, reject) => glob(
'**/*.mustache',
{ cwd: __dirname },
(error, files) => error ? reject(error) : resolve(files)
));
}
public serialize(templateData: ITemplateData, templateFiles: ITemplateFileMap): string {
return render(templateFiles.index, templateData, templateFiles);
}
public renderDirective(type: TypeRef): Promise<void> {
return this.renderFile(getFilenameOf(type), type);
}
public renderIndex(): Promise<void> {
return this.renderFile('index.html');
}
public renderType(type: TypeRef): Promise<void> {
return this.renderFile(getFilenameOf(type), type);
}
}
Contributors