Enhance graphql documentation with graphql schema descriptions

One of the main features of graphql is its self-documentation feature. Graphql runtime converts all of its schemas into documentation since each thing has a specific type in schema so it's easy to generate documentation.

Did you know you can enhance this documentation by using your comments? And it's not as hard as you think!

Let's start the implementation

Add comment to the schema type

You can write comments with tripe quotes above any type

    type Query {
        """ Get user return user based on user id """
        getUser(id: ID!): User
        """ posts return list of posts """
        posts:[Post]
    }

    type Mutation{
        updatePost(_id: ID, title: String, content: String):Post
        createPost(_id: ID, title: String!, content: String):Post
        login(email: String!, password: String!):AuthPayload
        registerUser(email: String!, password: String!, username: String):User
    }

    type AuthPayload{
        token: String
        user: User
    }

    type User {
        """ Database generated user id """
        _id: ID!
        """ Username of the user to uniquely identify the user """
        username: String!
        """ Email address of the user """
        email: String!
        """ List of posts associated with the user """
        posts: [Post]
    }

    type Post {
        _id: ID!
        title: String!
        content: String!
    }

As you can see I wrote comments for the query type of getUser and posts as shown in the code above. I also wrote comments for each field of type User by simply writing comments inside triple quotes for each field as shown.

The above will result in auto-generate documentation that looks as follows:

That's it, It's amazing to see documentation just by adding comments

I hope you like it!