Как добавить описание в поле "Язык схемы GraphQL"

Ответ 1

Если вы используете GraphQL.js версии 0.7.0 или выше, вы можете просто добавить комментарий непосредственно перед полем, типом или аргументом, который вы хотите описать. Например:

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

Ниже версии 0.7.0 невозможно добавить описания внутри языка схемы.

UPDATE: начиная с версии v0.12.3 вы должны использовать строковые литералы

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

Ответ 2

Это отличный вопрос! И на самом деле имеет отличную историю в мире graphql.

В репозитории graphql-js было задано несколько вопросов, обсуждений и запросов Pull, которые пытались обсудить возможный синтаксис, поскольку это было то, что было необходимо большинству членов сообщества. Благодаря Ли Байрону и этот запрос Pull мы можем фактически добавлять описания на язык схемы, используя традиционные комментарии.

Например,

// 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 name
  name: String!

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

И если мы используем graphql, новее чем 0.7.0, комментарии фактически превращаются в описание для полей или типов. Мы можем проверить это, выполнив запрос интроспекции в нашей схеме:

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

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

Что даст нам результат, который выглядит так:

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

И показывает нам, что комментарии # были включены в описание для полей/комментариев, на которые мы их помещаем.

Надеюсь, что это поможет!

Ответ 3

Если вы используете реализацию Java....

Для graphql-java версии 7.0 (последняя версия с этой записью) с первым подходом к схеме вы можете использовать комментарии над полем, типом или аргументом.

Строковые литералы не соответствуют синтаксису версии 7.0.