The main goal of API documentation is to help developers understand how to use an API. With GraphQL, developers often assume it's self-documenting capabilities are sufficient for anyone that consumes their GraphQL API. But did you ever validate this? Good API documentation offers both static and interactive ways to learn how to consume the API. API's that support GraphQL often only come with interactive documentation, in the shape of a GraphiQL Playground. 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. 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 talk explores which forms of documentation you can use and how they add value to your GraphQL API.

1. Roy Derks
@gethackteam
GraphQL Is No Excuse
To Stop Writing Docs

2. @gethackteam
What is documentation?

3. @gethackteam

4. @gethackteam
A little bit about
myself
fi
rst…

5. Roy Derks
@gethackteam
Hey! I'm Roy
an entrepreneur and software
engineer, author and public speaker
from The Netherlands.
+ more
@gethackteam

6. @gethackteam
What is documentation?

7. @gethackteam
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.
- the internet

8. @gethackteam
Documentation is communicable
material (1/2)

9. @gethackteam

10. @gethackteam

11. @gethackteam
Or for GraphQL

12. @gethackteam

13. @gethackteam
Let’s give it up for the
GraphiQL team 👏👏

14. @gethackteam
Documentation could be both
static and dynamic

15. @gethackteam
Documentation could be both
static and dynamic

16. @gethackteam
Documentation could be both
static and dynamic
- API Playgrounds
- Code examples
- GraphiQL

17. @gethackteam
Documentation is used to describe,
explain or instruct (2/2)

18. @gethackteam
1. describe 2. explain
3. instruct

19. @gethackteam
1. describe 2. explain
3. instruct

20. @gethackteam
describe
List of attributes:
API reference
SDK reference
…

21. @gethackteam
1. describe 2. explain
3. instruct

22. @gethackteam
explain
Explain concepts,
procedures or

23. @gethackteam
1. describe 2. explain
3. instruct

24. @gethackteam
instruct
Instruct on
installation, usage
or maintenance

25. @gethackteam
How are GraphQL APIs usually
documented?

26. @gethackteam
First, a hard question

27. @gethackteam
Is GraphQL really
self-documenting?

28. introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
@gethackteam

29. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
GraphiQL
* OPTIONAL

30. @gethackteam
Is GraphQL really
self-documenting?

31. @gethackteam
Only up to a small amount

32. @gethackteam
The power is in the schema and
introspection

33. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql

34. @gethackteam
Introspection exposes your
GraphQL schema

35. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
GraphiQL

36. @gethackteam
And can be used by tools
like GraphiQL

37. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
GraphiQL

38. @gethackteam
There are similar tools
like GraphiQL

39. @gethackteam
GraphQL Playground, Apollo Studio,
GraphQL Editor, …

40. @gethackteam
But are these tools enough?

41. 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.
- the internet
@gethackteam

42. 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.
- the internet
@gethackteam

43. @gethackteam
GraphiQL
Describe ✅
Explain
Instruct

44. @gethackteam
GraphiQL
Describe ✅
Explain
Instruct ✅

45. @gethackteam
Describe ✅
Explain?
Instruct ✅

46. @gethackteam
Description
OR
Explanation?

47. @gethackteam
"""
Multiline description of the User type
"""
type Customer {
address: Address
email: String
id: Int # Unique identifier of the customer in a single line
name: String
}
type Query {
"""
Will return a list of customers
More info in our documentation
"""
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
Schema annotations

48. @gethackteam
"""
Multiline description of the User type
"""
type Customer {
address: Address
email: String
id: Int # Unique identifier of the customer in a single line
name: String
}
type Query {
"""
Will return a list of customers
More info in our documentation
"""
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
Schema annotations

49. @gethackteam
GraphiQL (and others) lack in-depth
explain features

50. @gethackteam
What are we missing?
- Installation
- Authentication
- Troubleshoot
- …

51. @gethackteam
Earlier we learned:
Documentation could be both
static and dynamic

52. @gethackteam
GraphiQL is mostly dynamic, but
lacks space for explanations

53. @gethackteam
Space we need for text, graphics
and videos

54. @gethackteam
To explain how the GraphQL API
works in-depth

55. @gethackteam
And we can use introspect
to bootstrap it

56. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql

57. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
GraphiQL

58. @gethackteam
introspection
type Customer {
address: Address
email: String
id: Int
name: String
}
type Query {
getCustomerList: [Customer]
getCustomerById(id: ID!): Customer
}
schema
curl -X POST -H "Content-Type: application/json"
-d '{"query": "{ __schema { queryType { name } }"}'
https://my.graphql.server/graphql
GraphiQL
Static docs

59. @gethackteam
There are plenty of static
documentation generators

60. Magidoc SpectaQL
@gethackteam
DociQL

61. @gethackteam
They let you extend the introspected
docs with text, markdown, and JS

62. @gethackteam
So we can explain:
- Installation
- Authentication
- Troubleshoot
- …

63. @gethackteam
GraphiQL Static docs
GraphQL Documentation

64. @gethackteam
GraphiQL Static docs
GraphQL Documentation
Describe ✅
Explain
Instruct ✅
Describe ✅
Explain ✅
Instruct

65. @gethackteam
GraphiQL Static docs
GraphQL Documentation
❤ 🚀

66. Roy Derks
@gethackteam
Thank you!
Let’s stay in touch
stepzen.com
hackteam.io