Блог

У меня есть схема graphql, фрагмент которой выглядит следующим образом:

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

В graphiql есть поле описания, но оно всегда говорит «самоописательное». Как мне добавить описания в схему?

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

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

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

ОБНОВЛЕНИЕ: начиная с версии v0.12.3, вы должны использовать строковые литералы

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

}
  

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

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

Например,

 // 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!
}
`);
  

И, если мы используем 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's name"
            },
            {
              "name": "password",
              "description": "This is a user's password"
            }
          ]
        },
      ]
    }
  }
}
  

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

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

В случае, если вы используете реализацию Java….

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

Строковые литералы не являются допустимым синтаксисом начиная с версии 7.0.