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

Question

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?

Answer 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!  } 

Answer 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!