import ballerina/graphql;

service /graphql on new graphql:Listener(4000) {

    # Returns a person using the provided ID.
    # + id - The ID of the person
    # + return - The person with the requested ID
    resource function get profile(int id) returns Person? {
        if id == 1 {
            return {name: "Walter White", age: 52};
        } else if id == 2 {
            return {name: "Jesse Pinkman", age: 25};
        }
        return;
    }
}

# Represents a person.
# + name - The name of the person
# + age - The age of the person
type Person record {
    string name;
    int age;
};

Documentation

A GraphQL schema can include documentation for the schema. These documentation can help you to understand the schema.

In Ballerina, the Ballerina doc comments can be used to add documentation to various schema members.

For more information on the underlying package, see the GraphQL package.

import ballerina/graphql;
service /graphql on new graphql:Listener(4000) {
    # Returns a person using the provided ID.
    # + id - The ID of the person
    # + return - The person with the requested ID
    resource function get profile(int id) returns Person? {
        if id == 1 {
            return {name: "Walter White", age: 52};
        } else if id == 2 {
            return {name: "Jesse Pinkman", age: 25};
        }
        return;
    }
}
# Represents a person.
# + name - The name of the person
# + age - The age of the person
type Person record {
    string name;
    int age;
};
bal run graphql_documentation.bal
# Send a query to the GraphQL endpoint using a cURL command.
# The query used: { __schema { queryType { fields { name description type { name description fields { name description } } args { name description } } } } }
curl -X POST -H "Content-type: application/json" -d '{ "query": "{ __schema { queryType { fields { name description type { name description fields { name description } } args { name description } } } } }" }'
'http://localhost:4000/graphql'
{ "data": { "__schema": { "queryType": { "fields": [ { "name": "profile", "description": "Returns a person using the provided id.", "type": { "name": "Person", "description": "Represents a Person.", "fields": [ { "name": "name", "description": "The name of the person" }, { "name": "age", "description": "The age of the person" } ] }, "args": [ { "name": "id", "description": "The ID of the person" } ] } ] } } } }