Documenting GraphQL APIs

The main goal of API documentation is to help developers understand how to use an API.

Suppose you’ve just released a new API and created the documentation that other developers can use to understand how your API works. This documentation can usually be generated automatically if you’ve followed an API specification such as OpenAPI. An excellent way to write documentation is to create static documentation with interactive code examples, which will help people get started.

However, the first time you (or your users) use a GraphQL API can be very frustrating as GraphQL APIs typically only have an interactive playground. This playground is often created with GraphiQL, an interactive development environment (IDE), and serves as the primary form of documentation for most GraphQL APIs. Using GraphiQL, you can explore the API schema, compose GraphQL operations and execute them to get a response. A downside of having only this IDE is that it increases the complexity for newcomers to GraphQL as it assumes you’re already familiar with GraphQL.

But with GraphQL, you’re not limited to just an interactive playground, as you can create static or interactive documentation next to having this playground. This article explores which forms of documentation you can use and how they add value to your GraphQL API.

Using Introspection to Explore GraphQL

Any form of documentation that you write for a GraphLQ API starts with something called introspection. With introspection, you get more information about the schema of a GraphQL API, its types, and the possible operations. Using a GraphQL introspection query, the API will respond with details about the GraphQL endpoint you are introspecting.

An introspection query will look like this:

{
  __schema {
    queryType {
      name
    }
  }
}

This query will return all the possible queries that you can run with this GraphQL API, and as it’s executed directly on the server, it will update as the schema changes over time. Introspection can be used directly from the terminal using a curl request. This is a very basic yet efficient way to discover how you can use a GraphQL API and which operations and types are supported.

Using introspection is part of the GraphQL specification, but the option to use it is often disabled for production environments. By letting everyone introspect your endpoint, you could give away sensitive information. That’s why most companies don’t support introspection but let you inspect a GraphQL through a playground like GraphiQL or static/interactive documentation only.

Exploring GraphQL with GraphiQL

You’ve just learned that you can get all the information about a GraphQL schema, such as queries or mutation that you can execute and the types that they will return with an introspection query. But as introspection is often disabled on endpoints that run on production, companies use the GraphiQL playground as an alternative. When a playground is available, most GraphQL APIs will give you access to it when you visit the endpoint for the API in the browser.

The example GraphQL API that you see below was created with StepZen. For every GraphQL endpoint that you create with StepZen, you can access a GraphiQL playground that looks like this:

GraphiQL is a great way to explore a GraphQL API, as it lets you interact with it in an IDE. This IDE enables you to look at the schema, click through the possible operations, and more information about what fields or types are available. With GraphiQL you can send operations to the server and see what response they will generate.

When creating a GraphQL schema, you can also add descriptions for fields and types in the schema, which will become visible in GraphiQL. Although this makes the experience more complete, you still need to know how to compose a query with GraphQL to see the API response. The schema you can find in GraphiQL is helpful, but if you’re unfamiliar with GraphQL, this alone won’t bring you much further.

Provide Examples in Your GraphQL Documentation

Documentation should help developers understand how to use an API, and for GraphQL, both introspection and a GraphiQL playground are good starting points. But another goal is showing developers how to get from documentation to code, while introspection and the playground only provide the coding part. To give developers that use your GraphQL API more context on how to use it for their needs, some companies choose to accompany a playground with static or interactive documentation.

Static documentation can be a good addition, with a playground running on GraphiQL to make it interactive. The static documentation can give the developer all the information on how to compose operations, including code examples, and read the response from the playground later. Combining documentation with static examples with a GraphiQL playground gives developers all the tools they need to start using your API, even without knowing how GraphQL works.

Another thing that makes good documentation stand out is being up to date. If you use an introspection query or a playground to document your GraphQL API, the GraphQL engine makes sure that it follows any changes made to the schema of the API. If you choose to create (static) documentation yourself, it’s important to keep it updated. You can manually update it when you release a new feature or integrate CI/CD to generate new documentation for your API on deployment.

Create Static Documentation for GraphQL

Besides using introspection or GraphiQL to document your GraphQL API, you can also do this statically. This might feel familiar if you’ve used REST APIs in the past as those often have static documentation. To create static documentation for your GraphQL API you can use a library like SpectaQL. The static documentation that will be generated looks somewhat like the following:

This library uses the queries that you provide for your API together with your schema to create the documentation. If you’ve added descriptions in your schema these will be added to the documentation as well. To generate static documentation for your GraphQL using SDL you only have to install spectaql from npm and create a config file to define where your schema can be found:

spectaql:
  logoFile: ''

introspection:
  url: ''
  headers:
    Authorization: ''

info:
  title: ''
  description: ''

servers:
  - url: ''
    description: Production
    production: true

This configuration is all you need to generate the static documentation. The output can be hosted on any server as SpectaQL creates a JavaScript bundle for you.

Conclusion

We’ve explored multiple ways to document a GraphQL API using an introspection query, a playground like GraphiQL, or through (interactive) documentation. All these approaches use the GraphQL schema as their input to generate the documentation. Documentation should serve the needs of developers that want to use your API and take them from documentation to code using interactive code examples. You can achieve exactly that by enhancing the tools that GraphQL already offers, like the introspection query and GraphiQL.