Comment ajouter une description à un champ dans "GraphQL schema language" ?

Question

J'ai un schéma graphql, dont un fragment ressemble à ceci :

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

Dans graphiql, il y a un champ de description, mais il indique toujours "auto-descriptif". Comment puis-je ajouter des descriptions au schéma ?

Answer 1

Si vous utilisez GraphQL.js version 0.7.0 ou supérieure, vous pouvez simplement ajouter un commentaire directement avant le champ, le type ou l'argument que vous souhaitez décrire. Par exemple :

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

En dessous de la version 0.7.0, il n'est pas possible d'ajouter des descriptions dans le langage du schéma.

MISE À JOUR : depuis la version v0.12.3 vous devez utiliser littéraux de chaîne de caractères

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

C'est une excellente question ! Et a en fait une grande histoire dans graphql monde.

Il y a eu de multiples problèmes, discussions et demandes de téléchargement sur le site Web de la Commission européenne. graphql-js qui a essayé de discuter d'une syntaxe possible pour cela, car c'est quelque chose que beaucoup de membres de la communauté ont estimé nécessaire. Merci à Lee Byron et cette Pull Request En fait, nous pouvons ajouter des descriptions à un langage de schéma en utilisant les commentaires traditionnels.

Par exemple,

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

Et, si nous utilisons graphql qui est plus récent que 0.7.0 les commentaires sont en fait transformés en description des champs ou des types. Nous pouvons le vérifier en exécutant une requête d'introspection sur notre schéma :

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

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

Ce qui nous donnerait un résultat qui ressemble à :

{
  "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"
            }
          ]
        },
      ]
    }
  }
}

Et nous montre que le # ont été incorporés comme descriptions des champs/commentaires sur lesquels nous les avons placés.

J'espère que cela vous aidera !

Answer 3

Dans le cas où vous utilisez un Java mise en œuvre ....

Pour graphql-java version 7.0 (la dernière version au moment de la rédaction de cet article) avec une approche basée sur les schémas. commentaires au-dessus du champ, du type ou de l'argument.

Littéraux de chaîne de caractères son no syntaxe valide à partir de la version 7.0.