Static page generator for documenting GraphQL Schema
npm install @2fd/graphdoc
!npm (scoped)
!GitHub tag
* Facebook Test Star Wars
* Github GraphQL
* Pokemon GraphQL
``bash`
npm install -g @2fd/graphdoc
`bash`
> graphdoc -e http://localhost:8080/graphql -o ./doc/schema
`bash`
> graphdoc -s ./schema.graphql -o ./doc/schema
`bash`
> graphdoc -s ./schema.js -o ./doc/schema
> ./schema.graphql must be able to be interpreted with graphql-js/utilities#buildSchema
`bash`
> graphdoc -s ./schema.json -o ./doc/schema
> ./schema.json contains the result of GraphQL introspection query
`javascript
// package.json
{
"name": "project",
// [...]
"graphdoc": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
}
}
`
And execute
`bash`
> graphdoc
`bash
> graphdoc -h
Static page generator for documenting GraphQL Schema v1.2.0
Usage: graphdoc [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 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.
-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
`
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.
`typescript
/**
* PluginInterface
*/
export interface PluginInterface {
/**
* Return section elements that is going to be
* inserted into the side navigation bar.
*
* @example plain javascript:
* [
* {
* title: 'Schema',
* items: [
* {
* text: 'Query',
* href: './query.doc.html',
* isActive: false
* },
* // ...
* }
* // ...
* ]
*
* @example with graphdoc utilities:
* import { NavigationSection, NavigationItem } from 'graphdoc/lib/utility';
*
* [
* new NavigationSection('Schema', [
* new NavigationItem('Query', ./query.doc.html', false)
* ]),
* // ...
* ]
*
* @param {string} [buildForType] -
* the name of the element for which the navigation section is being generated,
* if it is undefined it means that the index of documentation is being generated
*/
getNavigations?: (buildForType?: string) => NavigationSectionInterface[] | PromiseLike
/**
* Return section elements that is going to be
* inserted into the main section.
*
* @example plain javascript:
* [
* {
* title: 'GraphQL Schema definition',
* description: 'HTML'
* },
* // ...
* ]
*
* @example with graphdoc utilities:
* import { DocumentSection } from 'graphdoc/lib/utility';
*
* [
* new DocumentSection('GraphQL Schema definition', 'HTML'),
* // ...
* ]
*
* @param {string} [buildForType] -
* the name of the element for which the navigation section is being generated,
* if it is undefined it means that the index of documentation is being generated
*
*/
getDocuments?: (buildForType?: string) => DocumentSectionInterface[] | PromiseLike
/**
* Return a list of html tags that is going to be
* inserted into the head tag of each page.
*
* @example
* [
* '',
* '',
* ]
*/
getHeaders?: (buildForType?: string) => string[] | PromiseLike
/**
* Return a list of abasolute path to files that is going to be
* copied to the assets directory.
*
* Unlike the previous methods that are executed each time that a page generated,
* this method is called a single time before starting to generate the documentation
*
* @example
* [
* '/local/path/to/my-custom-style.css',
* '/local/path/to/my-custom-image.png',
* ]
*
* there's will be copied to
* /local/path/to/my-custom-style.css -> [OUTPUT_DIRETORY]/assets/my-custom-style.css
* /local/path/to/my-custom-image.png -> [OUTPUT_DIRETORY]/assets/my-custom-image.png
*
* If you want to insert styles or scripts to the documentation,
* you must combine this method with getHeaders
*
* @example
* getAssets(): ['/local/path/to/my-custom-style.css']
* getHeaders(): ['']
*/
getAssets?: () => string[] | PromiseLike
}
`
To create your own plugin you should only create it as a plain objectconstructor
or a 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).graphdocPackag
* : 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
`typescript
// es2015 export constructor
export default class MyPlugin {
constructor(schema, projectPackage, graphdocPackag){}
getAssets() { / ... / }
/ ... /
}
`
`typescript`
// es2015 export plain object
export default cost myPlugin = {
getAssets() { / ... / },
/ ... /
}
`javascript
// export constructor
function MyPlugin(schema, projectPackage, graphdocPackage) { / ... / }
MyPlugin.prototype.getAssets = function() { / ... / };
/ ... /
exports.default = MyPlugin;
`
`javascript
// export plain object
exports.default = {
getAssets: function() { / ... / },
/ ... /
}
`
You can use the plugins in 2 ways.
#### Use plugins with command line
`bash`
> graphdoc -p graphdoc/plugins/default \
-p some-dependencie/plugin \
-p ./lib/plugin/my-own-plugin \
-s ./schema.json -o ./doc/schema
#### Use plugins with package.json
`javascript
// 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"
]
}
}
``
> TODO
> TODO