86

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?

1
  • 6
    PS hash your passwords kids! Oct 11, 2016 at 7:55

3 Answers 3

167

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!

}
4
18

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!

3
  • 1
    Very helpful thanks - I did search for a long time for an answer, and was struggling through lots of old issues - when the answer was so simple! :) Oct 11, 2016 at 8:03
  • Yes, took me a while to find as well. TYVM!
    – DJC
    Jul 11, 2017 at 23:53
  • I'm using graphql 0.12.3 and this isn't working for me. Description is always null using the code above.
    – Casey
    Jan 10, 2018 at 1:00
8

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.

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.