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.
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
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
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