graphqldoc

library2.5.2jsnpmunverified

Static page generator for documenting GraphQL schemas, version 2.5.2. A maintained fork of the unmaintained graphdoc package. Provides CLI and plugin system to generate documentation from live endpoints, IDL files, modular schemas, or introspection JSON. Outputs static HTML pages with customizable templates and plugins. Suitable for documenting GraphQL APIs in a project.

devops

npm install graphqldoc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQLDOC

graphqldoc

devopsjavascriptv2.5.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

graphqldoc (CLI)

✓ npx graphqldoc -e http://localhost:8080/graphql -o ./doc/schema

✗ graphqldoc (without npx if not installed globally)

CLI tool; best used via npx for temporary execution or globally installed. Not a library import.

PluginInterface (TypeScript)

✓ import type { PluginInterface } from 'graphqldoc'

✗ import { PluginInterface } from 'graphqldoc'

PluginInterface is a type exported for TypeScript; use 'import type' for type-only imports.

Default export (Plugin)

✓ export default class MyPlugin { /* ... */ }

✗ module.exports = MyPlugin

Plugin must be default export; CommonJS module.exports not supported as plugin export.

Install graphqldoc globally and generate documentation from a live endpoint, a schema file, or a JSON introspection result, then view help.

npm install -g graphqldoc graphqldoc -e http://localhost:8080/graphql -o ./doc/schema graphqldoc -s ./schema.graphql -o ./doc/schema graphqldoc -j ./schema.json -o ./doc/schema graphqldoc -h

Debug

Known issues

gotchaThe `-o` (output) directory must not exist unless `-f` (force) is used, otherwise graphqldoc will fail.

fix

Use `-f` flag to delete existing output directory or ensure it does not exist.

affects: >=2.0.0

gotchaSchema file must be parseable by GraphQL.js; for `-s`, it can be .graphql, .js, or .json. For .js, it must export a schema object compatible with graphql-tools.

fix

Ensure your schema file is valid and exports a GraphQLSchema object (for JS) or is valid IDL/JSON.

affects: >=2.0.0

deprecatedThe original `graphdoc` package is unmaintained; this fork is actively maintained.

fix

Use graphqldoc instead of graphdoc. Migration: replace `graphdoc` with `graphqldoc` in dependencies and commands.

affects: >=2.0.0

gotchaPlugins that mutate the schema object can affect other plugins; all plugins share the same schema reference.

fix

Do not modify the schema object directly. If you need to modify, clone it first.

affects: >=2.0.0

gotchaWhen using `-e` (endpoint), HTTP headers must be provided via `-x` (header) option; no built-in auth handling.

fix

Use `-x` to pass headers, e.g., `-x 'Authorization: Bearer token'`.

affects: >=2.0.0

gotchaThe `--query` option for querystring parameters is only used with `--endpoint`.

fix

Ensure you use `-e` when using `-q`.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Output directory already exists. Use --force to overwrite.

Output directory specified with `-o` already exists and `-f` not used.

fix

Add `-f` flag: graphqldoc -e http://... -o ./doc -f

Error: Cannot read property 'definitions' of undefined

Schema file is not a valid GraphQL IDL or introspection result, or file is missing.

fix

Verify the schema file exists and is valid: for .graphql, ensure it contains valid SDL; for .json, ensure it is a valid introspection result.

Error: Plugin must be a constructor or plain object with PluginInterface

Plugin export is not a default export or does not implement the proper interface.

fix

Use `export default class MyPlugin { ... }` or `export default { ... }` that implements PluginInterface.

Upgrade

Version history

2.5.2latest on npm

Audit

Dependencies

graphqloptionalPeer dependency for schema parsing and introspection; required unless using only live endpoint with introspection.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/CodeSignal/graphqldoc ↗

packagegraphqldoc ↗

homepagehttps://github.com/CodeSignal/graphqldoc#readme ↗