Static page generator for documenting GraphQL Schema

• demos
• install
• use
• plugin
• template
• contributors

Demos

• Facebook Test Star Wars
• Github V4 API
• Shopify API
• Pokemon GraphQL

Install

 npm install -g @2fd/graphdoc

Use

Generate documentation from live endpoint

> graphdoc -e http://localhost:8080/graphql -o ./doc/schema

Generate documentation from IDL file

> graphdoc -s ./schema.graphql -o ./doc/schema

Generate documentation from for the "modularized schema" of graphql-tools

> graphdoc -s ./schema.js -o ./doc/schema

./schema.graphql must be able to be interpreted with graphql-js/utilities#buildSchema

Generate documentation from json file

> graphdoc -s ./schema.json -o ./doc/schema

./schema.json contains the result of GraphQL introspection query

Puts the options in your package.json

// package.json{"name": "project","graphdoc": {"endpoint": "http://localhost:8080/graphql","output": "./doc/schema",}}

And execute

> graphdoc

Help

> graphdoc -h
Static page generator for documenting GraphQL Schema v2.4.0
Usage: node bin/graphdoc.js [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=graphdoc/plugins/default].
-t, --template Use template [default=graphdoc/template/slds].
-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 graphdoc version.
-h, --help Print this help

Plugin

In graphdoc 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 introspection query
• projectPackage: The content of package.json of current project (or the content of file defined with --config flag).
• graphdocPackage: The content of package.json of graphdoc.

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

// es2015 export constructorexportdefaultclassMyPlugin{constructor(schema,projectPackage,graphdocPackage){}getAssets(){/* ... */}}

// es2015 export plain objectexportdefaultcostmyPlugin={getAssets(){/* ... */},}

// export constructorfunctionMyPlugin(schema,projectPackage,graphdocPackage){/* ... */}MyPlugin.prototype.getAssets=function(){/* ... */};exports.default=MyPlugin;

// export plain objectexports.default={getAssets: function(){/* ... */}};

Use plugin

You can use the plugins in 2 ways.

Use plugins with command line

> graphdoc -p graphdoc/plugins/default \
-p some-dependencies/plugin \
-p ./lib/plugin/my-own-plugin \
-s ./schema.json -o ./doc/schema

Use plugins with package.json

// package.json{"name": "project","graphdoc": {"endpoint": "http://localhost:8080/graphql","output": "./doc/schema","plugins": ["graphdoc/plugins/default","some-dependencie/plugin","./lib/plugin/my-own-plugin"]}}

Build-in plugin

TODO

Template

TODO

Contributors

• dependabot-preview[bot]
• bitliner
• kbariotis
• 0xflotus
• Joatin
• shiroyuki
• kristiehowboutdat
• tony
• dnalborczyk