graphdoc
A static page generator that automatically creates documentation from any GraphQL schema.
What is graphdoc?
Graphdoc is a static page generator that automatically creates documentation for GraphQL schemas. It takes a GraphQL schema from various sources—like a live endpoint, a GraphQL IDL file, or a JSON introspection result—and generates a set of static HTML files that document all types, queries, mutations, and subscriptions. This helps developers and API consumers understand the GraphQL API without manually writing documentation.
GraphQL API developers and teams who need to generate and maintain up-to-date documentation for their GraphQL schemas, especially those working with Node.js projects.
Developers choose Graphdoc because it automates the documentation process, supports multiple schema input formats, and is extensible via plugins, ensuring documentation is always synchronized with the schema without manual effort.
Overview
Static page generator for documenting GraphQL Schema
Use Cases
Best For
- Generating static documentation for a GraphQL API from a live endpoint
- Documenting GraphQL schemas defined in IDL (.graphql) files
- Creating API documentation from JSON introspection query results
- Building custom documentation layouts via plugins and templates
- Integrating schema documentation generation into npm-based build processes
- Providing navigable reference docs for internal or public GraphQL APIs
Not Ideal For
- Projects needing interactive GraphQL playgrounds or live query execution within docs
- Teams requiring combined documentation for both GraphQL and REST APIs in one tool
- Environments with rapidly changing schemas where frequent static regeneration is impractical
Pros & Cons
Pros
Supports documentation generation from live GraphQL endpoints, GraphQL IDL files, JSON introspection results, and modularized schemas, as detailed in the use cases with examples like GitHub and Shopify.
Allows customization through plugins that implement the PluginInterface, enabling tailored content display and integration into specific workflows, though documentation notes it's a TODO area.
Uses templates to control the output's look and feel, providing flexibility for design, but the README admits this section is incomplete with a TODO note.
Can be configured via package.json or CLI options, simplifying integration into Node.js projects and build processes, as shown in the installation and use examples.
Cons
The README has 'TODO' sections for plugins and templates, indicating that key features lack comprehensive guides, forcing users to rely on source code or experimentation.
Generates only static HTML pages without interactive features like query execution or real-time schema updates, making it unsuitable for dynamic documentation needs.
Creating custom plugins requires understanding the PluginInterface and can be complex due to limited built-in examples or community resources, as hinted by the sparse plugin details.
Frequently Asked Questions
Related Projects
spectaqlAutogenerate static GraphQL API documentation
gqldocThe easiest way to make API documents for GraphQL
xydGenerate GraphQL API docs
graphql-markdownFlexible documentation for GraphQL powered with Docusaurus
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.