Automatically generating documentation is a dream come true for developers looking to focus on the code instead of copywriting. It’s also a dream for end users, who get documentation that’s up-to-date and reliable.
GraphQL is a popular query language that lets developers extract the information they need from APIs. Considering that there are over 21,000 public APIs listed on ProgrammableWeb, the odds are good that the need for GraphQL’s querying abilities is only going to become more extreme.
With GraphQL’s popularity on the rise, the need for GraphQL documentation generators is going to become more pressing, as well. We’ve compiled some of the best GraphQL documentation generators and tools, to save you precious hours documenting your code.
GraphQL Documentation Generators, Explorers and Tools: A Round-Up
Documentation generators let you focus on writing great code and tending to your customers and fellow programmer’s needs. They also ensure your documentation is always up-to-date, as it’s generated from the API itself.
Documentation explorers are equally as important. Developers can get lost looking for a particular query or file type, losing their momentum and writing clumsy code. GraphQL documentation explorers enable developers to understand syntax and browse the documentation in a useful way.
Finally, we’ve also compiled some useful GraphQL tools that will benefit your API development. They’ll help you make the most of GraphQL’s powerful, targeted querying ability.
GraphQL Documentation Generators
Looking for a clean, easy-to-use static documentation generator? GraphQL Docs by Scaphold.io produces minimalist, understandable documentation. It’s purportedly generated in under 10 seconds, simply by inputting a GraphQL endpoint URL. Once you’ve generated your static documentation you’re able to make it public or keep it private.
Graphdoc is an open-source equivalent of GraphQL Docs. Like GraphQL Docs, Graphcdoc also creates static documentation pages using only an endpoint URL. Graphdoc can be easily integrated into a number of different development environments, from Rails to Ruby to JSON.
Currently in a closed beta at time of writing, DocQL generates documentation directly from a GraphQL schema. Documentation pages are automatically created as subdomains of the ‘hubs.docql.io’ domain, but custom domains are possible. The documentation can be customized via a set of curated custom-built CSS themes. Future pending DocQL features include automatic updates, custom user guides in an “API Hub.”
DocQL’s ability to create user guides is a promising feature. You’re able to load a Git Repository as the source for your custom API guide, which is generated using a simple YAML based config file.
The only downside? DocQL costs money. It’s currently priced at $80/month, at the minimum. If you’re just experimenting with GraphQL documentation tools, you may do better experimenting with open source options first.
Graphqldoc by Mvochoa
If you’re looking for a simple, stripped down tool to translate a GraphQL schema into markdown language, this Markdown Generator by Mvochoa, a variation of Graphqldoc, could be just what you’re looking for.
GraphQL Documentation Explorers
GraphiQL (pronounced Graphical) is an in-browser Integrated Development Environment (IDE) for exploring GraphQL. This makes interacting with your GraphQL much more streamlined and easy to navigate. It also makes programming in GraphQL easier thanks to a detailed GUI.
GraphiQL features a window that shows all of the possible queries, fields, mutations, types, and if they’re required. GraphiQL also stays synced with GraphQL, removing any depreciated fields and types from the documentation. You won’t have to worry about writing defunct code, so everything you script is going to work.
GraphiQL also supports debugging as you go, offering hints and pointing out errors, making your coding process as smooth and fluid as possible. It comes equipped with a JSON viewer, as well, with all of the features you’d expect from that function. GraphiQL includes code folding, automatic indentation, copy support, and read-only so you won’t have to worry about accidentally deleting something.
Finally, GraphiQL makes it easy to share your work. The URL updates automatically when a query is edited, with all of the syntax intact. This makes it instantaneous to share work with your colleagues or get feedback on your work.
GraphiQL is also the documentation explorer that many other GraphQL environments are built on top of. If you’re going to be using GraphQL in any serious capacity, you’d do well to familiarize with this IDE.
- Automatic query completion
- Syntax highlighting
- Debugging as you type
- Documentation explorer
- JSON Viewer
- Work is easily shareable
GraphQL Playground is another in-browser IDE that’s based on GraphiQL. Actually, it’s built around GraphiQL. This means it functions similarly but offers additional features. These features are designed to make developer’s workflow fluid and seamless.
One of GraphiQL’s most beloved features is the built-in documentation explorer. It only offers one column for its explorer, however, which can make it troublesome to explore deeply nested types. GraphQL Playground, on the other hand, offers multiple explorer columns as well as keyboard-based navigation.
When multiple developers are working with the same API, sometimes commands can get broken. GraphQL Playground features an automatic schema reload, meaning the schema’s updated any time the API changes.
Finally, GraphQL Playground is a wonderful tool for collaborative GraphQL projects. Files can be shared directly to GraphQL Bin, which functions like Pastebin for GraphQL queries. It can also be embedded on your GraphQL server, either as a React component or as middleware between frameworks like Hapi, Koa, or Express.
GraphQL Playground is available as a standalone application that can be run locally on your machine.
- Multi-column schema explorer
- Custom headers
- Color schemes
- Improved Query history
- GraphQL subscription support
- Easily shareable for collaborations
- Keyboard navigation
- No easy way to close schema columns
APIs can become impossibly dense, making it difficult to visualize their data and workflow. GraphQL Voyager transforms your GraphQL API into a relational graph, visualizing the connections of your data once you set your root schema. It’s interactive, as well, allowing you to highlight the fields of different data types when they’re selected and link to the relevant data in the graph. GraphQL Voyager also features a left-hand column to describe field information and a visual interface for easy navigation.
- Visualizes complex data
- Makes data sortable
- Easy to navigate
Insominia is a powerful REST-based API endpoint testing tool. Insomnia’s motto is “debug like a Human, not a robot,” making its intentions fairly clear straight out of the gate. It’s a feature-rich environment to test your GraphQL API in a variety of ways.
Insomnia allows you to create HTTP requests, where you’re able to specify the URL, headers, and authorization in one query. Insomnia delivers details for every response, returning a status code, body, headers, and cookies.
Insomnia’s main perk is the ability to organize your files and projects. You’re able to create workspaces, nested folders, drag-and-drop requests, and import and export data easily.
Insomnia’s a free and open-source environment for Windows, Mac, and Linux, meaning nearly anybody can take advantage of its workflow optimization. This also means there’s a vibrant community of developers using Insomnia. This makes Insomnia’s ability to create plug-ins for the Insomnia community a bonus.
Insomnia generates code snippets for over 12 different languages. It also features a thorough documentation area where you can add special instructions, code snippets, and test data to certain calls or connections.
Finally, Insomnia allows you to view responses beyond XML and JSON. You’re able to view HTML pages, PDFs, images, SVGs, and audio files.
The Power of Auto-Generation With GraphQL
Automated writing has been a holy grail of automation, AI, and machine learning for some time. Some have already been enjoying some success. Automated Insights, for example, have been using their Wordsmith algorithm to translate data into readable text. They produce over 1 billion articles a year.
Technical writing is its own unique discipline. The ability to compose clean, clear copywriting is entirely different than the skill set necessary to write efficient, streamlined code. Thus, auto-generation is a godsend for developers as well as end users.
We’ve covered some of the best GraphQL documentation generators and explorers we’ve found to give you an idea of what’s out there and pick the perfect tool for your specific needs. All of these tools will help you make the most of GraphQL. You won’t waste any time rooting through the documentation files. You won’t have to write pages upon pages of documentation. It’ll free you up to do what you’re really here to do, writing clean, clear code and creating excellent apps.