Why you need static documentation for your GraphQL API

Sunny Pelletier — Tue, 17 May 2022 02:23:00 +0000

One of the most important things for any API is documentation. Whether this API is used internally inside your company or is publicly available, developers interacting with it need a way to know how it works and what they can do with it.

In this article, I will go over how GraphQL compares to REST in this matter, the different types of documentation and finally, present the most common and standard way to document your API.

Documenting: GraphQL vs REST

Now I know what you're thinking:

"But I don't like to write documentation"

-- Every developer ever

Believe it, you're not alone. Nobody likes to write documentation. For this reason, lazy but smart developers had a brilliant idea: auto-generate it.

Documenting REST

If you used REST before, there are many great tools that can do this, like Open-API, which generates a schema out of your endpoints. This schema can then be used to generate interactive or static documentation using Swagger-UI for instance.

But what about GraphQL?

GraphQL, unlike REST, doesn't need a tool like Open-API to generate a schema. It's built in!

However, the schema does not really constitute a documentation in itself. There needs to be something that parses this schema and converts it to some sort of human-readable documentation for it to be useful.

Types of documentation

Two different types of documentation were introduced earlier: static vs interactive. Let's go over each other to see their key differences.

Interactive documentation

By interactive documentation, I mean a documentation that interacts with your API directly. GraphiQL is probably the most popular tool out-there to do this.

This kind of documentation is great, because it allows developers to test their queries and see the results quite easily. It can also be referred to as a playground, meaning that it's used to play around with the API.

Static documentation

Static documentation, in opposition, does not interact with your API. It consists of static HTML pages that describes what is available and how to use it.

But which one is better?

To be fair, I was convinced that you did not need static documentation for GraphQL and that interactive docs were enough. That was until we actually started to have customers using our API.

Even though they had a playground at their disposition, customers were not able to figure out everything else on their own.

How do I authenticate?
How do I fetch this particular information?
Why do I get this error?
What the hell is GraphQL?

What we realised very fast is that a playground was not enough. We needed to document authentication flows, concepts, common use-cases, etc. And all this is impossible to do with tools like GraphiQL alone. Interactive documentation is useful once you know exactly how to query something, but is not efficient at teaching you how to get there.

The solution

The solution seemed very obvious: we need to use both. Both have their advantages, but together, they can do everything.

This may seem like a lot of extra-work, but this is actually the approach taken by many companies, like GitHub or Shopify. They provide a static API reference, along with a separated API explorer to test queries.

And all this does not actually require that much work, because GraphQL does the heavy-lifting for you with its schema.

How ?

So, for the interactive documentation, we simply decided to host an instance of GraphiQL that our customers can access if they want.

As for the static documentation, branding was an important criteria for us. We did not want our documentation to look like everyone else's.

Unfortunately, the existing open-source tooling was really not compatible with this need. The projects doing that were either unmaintained, almost impossible to customise or difficult to extend.

Given the circumstances, we took the initiative to create a new tool: A tool that would allow for extensive customisation, while also being simple to use.

That's how Magidoc, a static GraphQL documentation website generator was born. With this project, we aim to provide various documentation templates and starters that are easily customisable to generate useful documentation for any GraphQL API.

If you are interested in knowing more about it, learn how you can autogenerate GraphQL documentation for GraphQL using SDL files. To learn more about the tool itself, check out our GitHub repository!

Conclusion

API Documentation is essential for any API that is used by someone else than you, whether these people are inside or outside your organisation. It makes people free to discover, understand and use your API without any other human help.

GraphQL being pretty recent, there is not any standard on how to do it yet (and probably never will be). Static documentation combined with interactive documentation seems to be what most companies are leaning towards. As we are all different individuals and learn in different ways, some people will get started better using a playground and by playing with the API, while others will prefer to explore all the possibilities at a glance.

DEV Community: Sunny Pelletier