GraphQL schema HTML documentation generation, using graphdoc with Isolated Operations

---

Quick Start

1 . Add dependencies:

package.json:

  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-flexible": "1.0.2",

2 . If default options are not suitable, then configure graphdoc-plugin-operations:

package.json:

{
  "graphdoc-plugin-operations": {
    "documentTitle": "The Description",
    "navigationTitle": "The Operations",
    "eraseByNameRegex": "^someOperation\\w*",
    "eraseByDescriptionRegex": "@RemoveFromDocumentation",
    "extractParametersDoc": false,
    "enableAssets": false
  }
}

3 Use graphdoc-plugin-operations:

package.json:

  "scripts": {
    "doc": "graphdoc -p graphdoc/../../graphdoc-plugin-operations -p graphdoc/../../graphdoc-plugin-flexible  -p graphdoc/../../graphdoc-plugin-schema -s ./schema.graphql -o ./build/documentation"
  },
  "graphdoc-plugin-flexible": {
    "document.schema": { "disable": true }
  },
  "graphdoc-plugin-schema": {
    "enableAssets": false
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-schema": "2.0.0",

graphdoc-plugin-flexible is required to disable document.schema plugin and allow custom types.
graphdoc-plugin-schema will substitute disabled document.schema plugin when required, and "enableAssets": false to avoid assets duplication.
graphdoc/../../ this is required to get external plugins working in graphdoc.

---

Goals

graphdoc-plugin-operations provides a way document operations independently using graphdoc.

Options

package.json:

(default values)

{
  "graphdoc-plugin-operations": {
    "documentTitle": "Description",
    "navigationTitle": "Operations",
    "eraseByNameRegex": "^$",
    "eraseByDescriptionRegex": "^$",
    "extractParametersDoc": true,
    "enableAssets": true
  }
}

• documentTitle: title of the document section.
• navigationTitle: title of the operations section in the navigation.
• eraseByNameRegex: Regular Expression to be used to remove operations, based on name.
• eraseByDescriptionRegex: Regular Expression to be used to remove operations, based on description.
• extractParametersDoc: if set to false, parameters documentation will be stay on operation declaration.
• enableAssets: if set to false, then it will disable all the assets provided by the plugin, i.e. script and css files will not be included.
  • graphdoc-plugin-operations uses exactly the same assets that graphdoc-plugin-schema and document-schema use.

The following shows where the documentTitle, the navigationTitle and the “code block” are located, using the example documentation created by graphdoc, Pokemon GraphQL HTML Documentation, using Pokemon GraphQL schema:

Extracted Parameters Documentation

Extracted

Not Extracted

Using/Configuration

• To use graphdoc-plugin-operations is necessary that document-schema plugin is disabled (since it doesn’t allow custom types), use graphdoc-plugin-flexible plugin:

package.json

  "scripts": {
    "doc": "graphdoc -p graphdoc/../../graphdoc-plugin-operations  -p graphdoc/../../graphdoc-plugin-flexible -s ./schema.graphql -o ./build/documentation"
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2"
  },
  "graphdoc-plugin-flexible": {
    "document.schema": { "disable": true }
  },
  "devDependencies": {
    "@2fd/graphdoc": "2.4.0",
    "graphdoc-plugin-flexible": "1.0.2",
    "graphdoc-plugin-operations": "2.2.0",
    "graphdoc-plugin-schema": "2.0.0",

You can use graphdoc-plugin-schema plugin as an alternative to document-schema plugin.

• main.mustache template may need some changes in other to get a better view, e.g.:

  {{#type}}
  {{^type.operationName}}<p class=”slds-text-title–caps slds-text-color–weak”>{{type.kind}}</p>{{/type.operationName}}
  {{#type.operationName}}<p class=”slds-text-title–caps slds-text-color–weak”>Operation</p>{{/type.operationName}}
  {{/type}}

Online Examples

• Pokemon GraphQL schema: Project and Online generated documentation.
• Github GraphQL schema: Project and Online generated documentation.

---

Prerequisites

• "@2fd/graphdoc": "2.4.0".

graphdoc can work with older versions of GraphQL (description syntax: #), and new versions (description syntax: “””), How to configure graphdoc.

---

Main documentation

Back to homepage