Roy Derks - GraphQL Isn’t An Excuse To Stop Writing Docs

Roy Derks

Developer Experience & Relations at StepZen

Roy's presentation (video recording)

Roy's slides

Q&A

• How is documenting a Graphql API different from other types of APIs?
• How do you embed examples in the GraphQL schema?
• So if we already have standards and guidelines for REST and OpenData, we could use the same rules for descriptions?

In the presentation, you can hear about:

• What documentation is?
• How does it adhere to GraphQL?
• Is GraphiQL really self-documentation?

What is documentation?

”Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance, and use.”

Documentations can also be:

• Static (non-interactive): e.g. user manual, Rosetta Stone, assembly instruction, etc.
• Dynamic (interactive): e.g. GraphiQL, GraphQL Playground, Apollo Studio, GraphQL Editor, etc.

What is GraphiQL?

It is an interactive playground HDI for exploring GraphQL APIs. GraphQL APIs rely on a GraphQL schema that can usually be introspected, so computers can read the schema and then extrapolate it in any way they like. A common way is doing this in GraphiQL, which is dynamic documentation because you can interact with the product directly.

Is GraphiQL really self-documentation?

GraphiQL is self-documenting but only to a small amount.

• It describes what the GraphQL API looks like.
• It instructs because you can actually use it, try it out.
• But: it’s lacking in-depth explanation feature (e.g. how to use this GraphQL API, do we need to install any libraries, how to authenticate, what the error message means, are there any software requirements, etc.).

GraphiQL is mostly dynamic but lacks space for explanations, the space we need for text, graphics, and videos.

Solution

Using static documentation and enhancing them with GraphiQL. Many static documentation generators (e.g. Magidoc, SpectaQL,DociQL, etc.) for GraphQL use the same format and schema as GraphiQL. This also makes updating both static and dynamic documentation easier because they have the same source. Static documentation can be further enhanced with videos, graphics, or more text. You can also embed or put links to GraphiQL in your static documentation.

Conclusion

”So together they are actually a rocket ship, because this way you have static documentation and dynamic documentation all coming from one GraphQL schema. And you can do all three things that you like to do with your API documentation, in this scenario GraphQL, which is describing, explaining, and instructing people how to use a product.”