web-dev-qa-db-fra.com

Comment ajouter une description à un champ dans "Langage schématique GraphQL"

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

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

Dans graphiql, il existe un champ de description, mais il est toujours dit "auto-descriptif". Comment ajouter des descriptions au schéma?

javascriptgraphqlapollo-server
50
derekdreery

Si vous utilisez GraphQL.js version 0.7.0 ou ulté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!
}

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

UPDATE: depuis la version v0.12. vous devriez utiliser littéraux de chaîne

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

}
93
davidyaha

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

Il y avait plusieurs problèmes, discussions et demandes d'extraction sur le graphql-js _ repo qui a essayé de discuter de la syntaxe possible pour cela, car c’était quelque chose que beaucoup de membres de la communauté jugeaient nécessaire. Grâce à Lee Byron et cette demande d'extraction , nous pouvons en fait ajouter des descriptions à un langage de schéma en utilisant des 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 c'est plus récent que 0.7.0, les commentaires sont réellement transformés en description pour les champs ou les 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 # _ commentaires ont été incorporés dans les descriptions des champs/commentaires sur lesquels nous les avons insérées.

J'espère que ça t'as aidé!

9
Josh Black

Si vous utilisez une implémentation Java ....

Pour graphql-Java version 7.0 (la dernière version en date de cette écriture) avec une approche de schéma, vous pouvez utiliser commentaires au-dessus du champ, du type ou de l'argument.

Les littéraux de chaîne ne sont pas syntaxe valide à partir de la version 7.0.

6
Fabian