Explaining in GraphQL is easy. Write single line comments with #
. Offer more verbosity in multi-line descriptions with bracketing """
.
Single Line Comment
Start exactly with #
to comment a simple single line.
# A snack may or may not be delicious.
type Snack {
name: String!,
delicious: Boolean!
}
Perfectly safe in a GraphQL schema.
Multi-Line Description
Bracket a multi-line comment with """
. GraphQL schema tools are smart. Multi-line descriptions are useful to tools like Graphiql.
"""
A shirt.
It is a really simple type.
"""
type Shirt {
"""
The size of the shirt, like small or medium.
The value depends on the language of the user.
"""
size: String!,
threads: Int!,
thickness: Float!
}
Also safe in a GraphQL schema.
Query Comment
A single line comment is safe in a query. A multi-line description is not.
{
snack {
# this comment is safe
name
}
}
Possible in a GraphQL query.
Lack of comments is like a pandemic
GraphQL is for people. I don't disagree with code clarity as documentation. Sometimes people who have nothing to do with code may read a GraphQL text block. It's shocking. Let's not forget that comments are fundamentally for our hyper connected readers. I don't know if there is a better way.
Top comments (0)