How do I add a description to a field in "GraphQL schema language"

I have a graphql schema, a fragment of which looks like this:

type User {
    username: String!
    password: String!
}

In graphiql, there is a description field, but it always says "self-descriptive". How do I add descriptions to the schema?

Solution 1:

If you're using GraphQL.js version 0.7.0 or above, you can simply add a comment directly before the field, type, or argument you want to describe. For example:

# A type that describes the user
type User {
     # The user's username, should be typed in the login field.
     username: String!
     # The user's password.
     password: String!
}

Below version 0.7.0 it is not possible to add descriptions inside the schema language.

UPDATE: since version v0.12.3 you should use string literals

"""
A type that describes the user. Its description might not 
fit within the bounds of 80 width and so you want MULTILINE
"""
type User {
     "The user's username, should be typed in the login field."
     username: String!
     "The user's password."
     password: String!

}

Solution 2:

This is a great question! And actually has a great history in graphql world.

There were multiple issues, discussions, and Pull Requests on the graphql-js repo that tried to discuss possible syntax for this, as it was something that a lot of members of the community felt were needed. Thanks to Lee Byron and this Pull Request, we can actually add descriptions to a schema language by using traditional comments.

For example,

// Grab some helpers from the `graphql` project
const { buildSchema, graphql } = require('graphql');

// Build up our initial schema
const schema = buildSchema(`
schema {
  query: Query
}

# The Root Query type
type Query {
  user: User
}

# This is a User in our project
type User {
  # This is a user's name
  name: String!

  # This is a user's password
  password: String!
}
`);

And, if we're using graphql that's newer than 0.7.0, the comments are actually turned into the description for the fields or types. We can verify this by running an introspection query on our schema:

const query = `
{
  __schema {
    types {
        name
        description,
        fields {
            name
            description
        }
    }
  }
}
`;

graphql(schema, query)
  .then((result) => console.log(result));

Which would give us a result that looks like:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "User",
          "description": "This is a User in our project",
          "fields": [
            {
              "name": "name",
              "description": "This is a user's name"
            },
            {
              "name": "password",
              "description": "This is a user's password"
            }
          ]
        },
      ]
    }
  }
}

And shows us that the # comments were incorporated as the descriptions for the fields/comments that we put them on.

Hope that helps!

Solution 3:

In case you're using a Java implementation ....

For graphql-java version 7.0 (the latest version as of this writing) with a schema first approach, you can use comments above the field, type, or argument.

String literals are not valid syntax as of version 7.0.