用于记录 GraphQL Schema 的静态页面生成器
演示文稿
- Facebook 测试 星球大战
- Github 图形QL
- Pokemon 图形QL
安装
npm install -g @2fd/graphdoc
使用
从活端生成文档
> graphdoc -e http://localhost:8080/graphql -o ./doc/schema
从 IDL 文件生成文档
> graphdoc -s ./schema.graphql -o ./doc/schema
生成文档 "模式化计划" 图表ql工具
> graphdoc -s ./schema.js -o ./doc/schema
从 json 文件生成文档
> graphdoc -s ./schema.json -o ./doc/schema
./schema.json包含 图QL 内向查询
将选项放入 package.json
// package.json
{
"name": "project",
// [...]
"graphdoc": {
"endpoint": "http://localhost:8080/graphql",
"output": "./doc/schema",
}
}
执行
> graphdoc
帮助
> 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
插件
在图文件中,插件只是控制显示内容的对象 在文档的每一页.
此对象只应执行 PluginInterface。 。 。 .
/**
* 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<NavigationSectionInterface[]>;
/**
* 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<DocumentSectionInterface[]>;
/**
* Return a list of html tags that is going to be
* inserted into the head tag of each page.
*
* @example
* [
* '<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>',
* '<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">',
* ]
*/
getHeaders?: (buildForType?: string) => string[] | PromiseLike<string[]>;
/**
* 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(): ['<link href="assets/my-custom-style.css" rel="stylesheet">']
*/
getAssets?: () => string[] | PromiseLike<string[]>;
}
制作一个插件
要创建自己的插件, 您只应该创建为 plain object
或一个 constructor 并导出为 default
如果您将插件导出为构造器, 当您要初始化时, 将获得三个参数
schema: 全部结果 图QL 内向查询projectPackage页:1package.json当前项目(或定义为--config旗帜).graphdocPackag页:1package.json图表文件.
出于性能原因,所有插件都收到同一对象的引用 因此,不应该直接修改它们,因为它可能影响行为 其他插件(当然除非您的意图)
实例
// es2015 export constructor
export default class MyPlugin {
constructor(schema, projectPackage, graphdocPackag){}
getAssets() { /* ... */ }
/* ... */
}
// es2015 export plain object
export default cost myPlugin = {
getAssets() { /* ... */ },
/* ... */
}
// export constructor
function MyPlugin(schema, projectPackage, graphdocPackage) { /* ... */ }
MyPlugin.prototype.getAssets = function() { /* ... */ };
/* ... */
exports.default = MyPlugin;
// export plain object
exports.default = {
getAssets: function() { /* ... */ },
/* ... */
}
使用插件
您可以以两种方式使用插件 .
使用带有命令行的插件
> graphdoc -p graphdoc/plugins/default \
-p some-dependencie/plugin \
-p ./lib/plugin/my-own-plugin \
-s ./schema.json -o ./doc/schema
使用插件为 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"
]
}
}
内建插件
开始
模板
开始