Graphdoc

Static page generator for documenting GraphQL Schema

README

Static page generator for documenting GraphQL Schema

build coverage
npm
tag

- use

Demos


- Facebook Test Star Wars

Install


  1. ``` sh
  2.   npm install -g @2fd/graphdoc
  3. ```

Use


Generate documentation from live endpoint


  1. ``` sh
  2.   > graphdoc -e http://localhost:8080/graphql -o ./doc/schema
  3. ```

Generate documentation from IDL file


  1. ``` sh
  2.   > graphdoc -s ./schema.graphql -o ./doc/schema
  3. ```

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


  1. ``` sh
  2.   > graphdoc -s ./schema.js -o ./doc/schema
  3. ```

[./schema.graphql](https://github.com/2fd/graphdoc/blob/master/test/starwars.graphql) must be able to be interpreted


Generate documentation from json file


  1. ``` sh
  2.   > graphdoc -s ./schema.json -o ./doc/schema
  3. ```

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

query](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql)


Puts the options in your package.json


  1. ``` js
  2.   // package.json

  3.   {
  4.     "name": "project",
  5.     "graphdoc": {
  6.       "endpoint": "http://localhost:8080/graphql",
  7.       "output": "./doc/schema",
  8.     }
  9.   }
  10. ```

And execute

  1. ``` sh
  2.   > graphdoc
  3. ```

Help


  1. ``` sh

  2.   > graphdoc -h
  3.   
  4.     Static page generator for documenting GraphQL Schema v2.4.0

  5.     Usage: node bin/graphdoc.js [OPTIONS]

  6.     
  7.     [OPTIONS]:
  8.     -c, --config                   Configuration file [./package.json].
  9.     -e, --endpoint                 Graphql http endpoint ["https://domain.com/graphql"].
  10.     -x, --header                   HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"].
  11.     -q, --query                    HTTP querystring for request (use with --endpoint) ["token=cb8795e7"].
  12.     -s, --schema, --schema-file    Graphql Schema file ["./schema.json"].
  13.     -p, --plugin                   Use plugins [default=graphdoc/plugins/default].
  14.     -t, --template                 Use template [default=graphdoc/template/slds].
  15.     -o, --output                   Output directory.
  16.     -d, --data                     Inject custom data.
  17.     -b, --base-url                 Base url for templates.
  18.     -f, --force                    Delete outputDirectory if exists.
  19.     -v, --verbose                  Output more information.
  20.     -V, --version                  Show graphdoc version.
  21.     -h, --help                     Print this help


  22. ```

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](https://github.com/2fd/graphdoc/blob/master/lib/interface.d.ts#L12-L117).

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


  1. ```typescript
  2.   // es2015 export constructor

  3.   export default class MyPlugin {

  4.     constructor(schema, projectPackage, graphdocPackage) {}

  5.     getAssets() {
  6.       /* ... */
  7.     }
  8.   }
  9. ```

  1. ```typescript
  2.   // es2015 export plain object

  3.   export default cost myPlugin = {
  4.     getAssets() {
  5.       /* ... */
  6.     },
  7.   }
  8. ```

  1. ``` js
  2.   // export constructor

  3.   function MyPlugin(schema, projectPackage, graphdocPackage) {
  4.     /* ... */
  5.   }

  6.   MyPlugin.prototype.getAssets = function() {
  7.     /* ... */
  8.   };

  9.   exports.default = MyPlugin;
  10. ```

  1. ``` js
  2.   // export plain object

  3.   exports.default = {
  4.     getAssets: function() {
  5.       /* ... */
  6.     }
  7.   };
  8. ```

Use plugin


You can use the plugins in 2 ways.

Use plugins with command line


  1. ``` sh
  2.   > graphdoc -p graphdoc/plugins/default \
  3.   -p some-dependencies/plugin \
  4.   -p ./lib/plugin/my-own-plugin \
  5.   -s ./schema.json -o ./doc/schema
  6. ```

Use plugins with package.json


  1. ``` js
  2.   // package.json

  3.   {
  4.     "name": "project",
  5.     "graphdoc": {
  6.       "endpoint": "http://localhost:8080/graphql",
  7.       "output": "./doc/schema",
  8.       "plugins": [
  9.         "graphdoc/plugins/default",
  10.         "some-dependencie/plugin",
  11.         "./lib/plugin/my-own-plugin"
  12.       ]
  13.     }
  14.   }
  15. ```

Build-in plugin


TODO


Template


TODO


Contributors


- [ dependabot-preview[bot]](https://github.com/apps/dependabot-preview)- [ bitliner](https://github.com/bitliner)- [ kbariotis](https://github.com/kbariotis)- [ 0xflotus](https://github.com/0xflotus)- [ Joatin](https://github.com/Joatin)- [ shiroyuki](https://github.com/shiroyuki)- [ kristiehowboutdat](https://github.com/kristiehowboutdat)- [ tony](https://github.com/tony)- [ dnalborczyk](https://github.com/dnalborczyk)