如何在“GraphQL模式语言”中向字段添加描述

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!

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