APIs are supposed to create less work, not more. Conceptualizing, designing, developing, then deploying an API is already a Herculean task. Creating API documentation is like a second full-time job, and one that’s nearly as important as the first. Unfortunately, not all programmers are trained to be technical writers. Just because you know how to create an API doesn’t mean you know how to explain it in clear, concise, or engaging ways.

Lack of time and design abilities isn’t the only reason to look into autogenerating API documentation, either. Automating API documentation ensures that your documentation is also up-to-date and consistent.

With all of these advantages, why wouldn’t you want to autogenerate your API documentation?

GraphQL has been one of the most popular and widely adopted API structures in recent years, thanks to its ability to resolve over- and underfetching, for one thing. GraphQL’s consistent structure also makes it ideal for autogenerating API documentation.

We’re even starting to see some dedicated tools for automating GraphQL API documentation, which we’ll explore below.

1. Determine Your Requirements

One of the main reasons GraphQL’s gotten so popular is its uniformity. It follows a routine, consistent format, so it’s incredibly easy to work with. Every GraphQL API call returns data in a standard way. Just because it’s there doesn’t mean it needs to be included in your API documentation, though.

If you’re creating your own automated GraphQL API documentation instead of working with one of the tools that are already out there, you should think about what you want to be included in your API documentation.

Examples of the data returned by a GraphQL API call include:

• Descriptions
• Types
• Fields
• Arguments
• Queries and Mutations
• Required-ness of things
• Default values
• Examples
• 1-off “undocumented” support
• Broad “undocumented” support

Consider These 5 GraphQL API Documentation Tools

One of the advantages of working with popular tools is you don’t need to recreate the wheel every time you start a new project. There are A LOT of GraphQL users out there. That means there are quite a few GraphQL API tools already available, as well.

Even better, many of them are free and open source. Most will be more than adequate for autogenerating API documentation.

1. SpectaQL

First, there’s SpectaQL, an open-source tool for generating static GraphQL API documentation written in Node.js. SpectaQL creates sleek, modern-looking API documentation following a three-column format. It’s a premade solution, but it’s very customizable if you’re willing to dig into the code.

2. Magidoc

There’s also a tool called Magidoc which also creates static API documentation based on either a GraphQL schema definition language (SDL) or from a live endpoint using the introspection query. Static API documentation isn’t Magidoc’s only application, either. You can even use the open-source tool to create custom web pages from simple markdown files.

3. DociQL

DociQL is another open-source tool for automating API documentation for GraphQL that shares numerous similarities with Magidoc. It also creates static three-column API documentation from an API endpoint via the introspection query.

4. Graphql-docs

Then there’s Graphql-docs, another open-source tool for automatically generating static API documentation that we first discovered via our GraphQL documentation generator from a few years ago. Graphql-docs exposes a single React component to a GraphQL endpoint.

5. GraphDoc

Finally, there’s GraphDoc, another open-source tool that creates a static API documentation page from a GraphQL schema.

This brings us to our next tip…

Learn The GraphQL Schema

Part of what makes GraphQL so easy and efficient to work with is its schema. The GraphQL schema defines the shape of the returned data. It uses a standardized hierarchy of fields and types and specifies the queries and mutations.

The GraphQL schema follows the SDL format and is stored in a .YAML file in the API programming directory. The GraphQL schema specifies what object type each field can accept. GraphQL supports the following object types:

• scalar
• object
• enum
• union
• interface

GraphQL schema can also include descriptions, which you can use to make your automated API documentation as detailed and useful as possible. If you opt to use SpectaQL to autogenerate your API documentation, it includes a default YAML file that takes care of everything for you.

SpectaQL is also highly customizable, though, which means you can configure the output nearly any way you can imagine. Here’s an example of a working YAML file configured to work with SpectaQL:

spectaql:
  logoFile: ./test/fixtures/logo.png
  faviconFile: ./test/fixtures/favicon.png
  displayAllServers: true

introspection:
  removeTrailingPeriodFromDescriptions: false
  schemaFile: ./examples/data/schema.gql
  metadataFile: ./examples/data/metadata.json
  dynamicExamplesProcessingModule: ./examples/customizations/examples
  queryNameStrategy: capitalizeFirst
  fieldExpansionDepth: 2

extensions:
  graphqlScalarExamples: true

info:
  title: GraphQL API Reference
  description: Welcome to the party!
  termsOfService: https://www.example.com/terms
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-introItems:
    - title: Important thing 1
      description: Some important stuff we wanted you to know. Supports `markdown`

servers:
  - url: https://staging.example.com/graphql
    description: Staging
  - url: https://example.com/graphql
    description: Production
    production: true
    headers:
      - name: Authorization
        example: Bearer <YOUR_TOKEN_HERE>
        comment: Your foo from bar

Following the SDL format for your schema, you can simply supply the .YAML file to one of the documentation generators we mentioned above, and you’ll have working static API documentation in a couple of minutes or less.

Taking the time to become comfortable with GraphQL schema will help you make the most of working with SpectaQL should you decide to go that route. Especially if you’re planning on implementing your own automated documentation, you need to become familiar with GraphQL schema.

How To Autogenerate GraphQL API Documentation: Final Thoughts

GraphQL isn’t going anywhere. Neither is the need for API documentation automation. Autogenerating API documentation has become increasingly prevalent since the widespread adoption of Swagger and OpenAPI. Considering these trends, it seems undeniable that GraphQL will follow suit.

Automated API documentation also lays to rest the artificial dichotomy between design-first and code-first APIs. When you follow a standardized format for your API, it ensures that computers and people alike will be able to read and understand your API.

Using a tool like SpectaQL ensures that your API documentation will always be correct. It also saves you from having to spend unnecessary time, money, energy, and resources creating documentation when you could be writing code, marketing your product, or taking care of your customers.