@2fd/graphdoc 中文文档教程

Question

Static page generator for documenting GraphQL Schema

Demos

• Facebook Test Star Wars
• Github GraphQL
• 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 必须能够用 graphql-js/utilities#buildSchema

Generate documentation from json file

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

./schema.json 包含 GraphQL 自省查询

Puts the options in your package.json

     // package.json

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

并执行

    > graphdoc

Help

    > 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

Plugin

在 graphdoc 中，插件只是一个控制显示内容的对象 在文档的每一页上。

该对象应仅实现 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[]>;
    }

Make a Plugin

要创建您自己的插件，您应该只将其创建为普通对象 或 constructor 并将其导出为 default

如果您将插件导出为构造函数，则在初始化时， 将收到三个参数

• schema: The full the result of GraphQL instrospection query
• projectPackage: 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.

出于性能原因，所有插件都收到对同一对象的引用 因此不应直接修改它们，因为它可能会影响行为 其他插件（当然除非您有意）

Examples

    // 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() { /* ... */ },
        /* ... */
    }

Use plugin

您可以通过两种方式使用这些插件。

Use plugins with command line

    > 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

     // 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

待办事项

Template

_