Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/2fd/graphdoc
Static page generator for documenting GraphQL Schema
https://github.com/2fd/graphdoc
documentation documentation-generator documentation-tool graphql
Last synced: 2 days ago
JSON representation
Static page generator for documenting GraphQL Schema
- Host: GitHub
- URL: https://github.com/2fd/graphdoc
- Owner: 2fd
- License: mit
- Created: 2016-08-09T01:33:28.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-31T01:32:39.000Z (almost 2 years ago)
- Last Synced: 2025-01-16T19:17:56.818Z (9 days ago)
- Topics: documentation, documentation-generator, documentation-tool, graphql
- Language: TypeScript
- Homepage: https://2fd.github.io/graphdoc
- Size: 3.49 MB
- Stars: 1,559
- Watchers: 14
- Forks: 135
- Open Issues: 98
-
Metadata Files:
- Readme: README.handlebars
- License: LICENSE
Awesome Lists containing this project
- awesome - graphdoc - Static page generator for documenting GraphQL Schema (TypeScript)
- awesome-graphql - graphdoc - Static page generator for documenting GraphQL Schema. (Tools / Julia Libraries)
- awesome-ccamel - 2fd/graphdoc - Static page generator for documenting GraphQL Schema (TypeScript)
- awesome-list - graphdoc
- awesome - 2fd/graphdoc - Static page generator for documenting GraphQL Schema (TypeScript)
- awesome - 2fd/graphdoc - Static page generator for documenting GraphQL Schema (TypeScript)
README
# {{project.description}}
[](https://github.com/2fd/graphdoc/actions?query=workflow%3Abuild+branch%3Amaster+)
[](https://coveralls.io/github/2fd/graphdoc?branch=master)
- [demos](#demos)
- [install](#install)
- [use](#use)
- [plugin](#plugin)
- [template](#template)
- [contributors](#contributors)
## Demos
- Facebook Test [Star Wars](https://2fd.github.io/graphdoc/star-wars)
- [Github V4 API](https://2fd.github.io/graphdoc/github)
- [Shopify API](https://2fd.github.io/graphdoc/shopify/)
- [Pokemon GraphQL](https://2fd.github.io/graphdoc/pokemon)
## Install
```bash
npm install -g @2fd/graphdoc
```
## Use
### Generate documentation from live endpoint
```bash
> graphdoc -e http://localhost:8080/graphql -o ./doc/schema
```
### Generate documentation from IDL file
```bash
> graphdoc -s ./schema.graphql -o ./doc/schema
```
### Generate documentation from for the ["modularized schema"](http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#modularizing) of graphql-tools
```bash
> graphdoc -s ./schema.js -o ./doc/schema
```
> [`./schema.graphql`](https://github.com/2fd/graphdoc/blob/master/test/starwars.graphql) must be able to be interpreted
> with [graphql-js/utilities#buildSchema](http://graphql.org/graphql-js/utilities/#buildschema)
### Generate documentation from json file
```bash
> graphdoc -s ./schema.json -o ./doc/schema
```
> `./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`
```javascript
// package.json
{
"name": "project",
"graphdoc": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
}
}
```
And execute
```bash
> graphdoc
```
### Help
```bash
> graphdoc -h
{{{bash "node ./bin/graphdoc.js --no-color --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`](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](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql)
- `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
```typescript
// es2015 export constructor
export default class MyPlugin {
constructor(schema, projectPackage, graphdocPackage) {}
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() {
/* ... */
}
};
```
### Use plugin
You can use the plugins in 2 ways.
#### Use plugins with command line
```bash
> 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`
```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"
]
}
}
```
### Build-in plugin
> TODO
## Template
> TODO
## Contributors
{{#each contributors}}- [
{{{login}}}]({{{html_url}}})
{{/each}}