Motivation

Documentation is at the heart of GraphQL. Its core features makes up for great self documented APIs. From a consumer's perspective, it usually comes in the form of types, clear expectations and precise error messages. The standards also make it easy to build playgrounds, which come with many implementations. The typical playground offers a way to browse the API and learn more about its queries and mutations.

But while playgrounds are a great way to play around with an API, they are not necessarily the best first-time experience. This is especially true for GraphQL which may look a bit alien compared to the traditional, popular and mature REST approach. So a playground alone might not be enough, especially for public APIs targeted to teams with varying backgrounds and technologies.

This is the gap that this plugin tries to fill. Its goal is to generate documentation that is easy to browse and share with minimum prior experience. To reach this goal, it takes most of its ideas from GitHub's GraphQL API documentation.