javascript - tutorial - ¿Cómo agrego una descripción a un campo en "Lenguaje de esquema GraphQL"?

graphql api apollo

Question

Tengo un esquema graphql, un fragmento del cual se ve así:

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

En graphiql, hay un campo de descripción, pero siempre dice "auto-descriptivo". ¿Cómo agrego descripciones al esquema?

Answer 1

¡Esta es una gran pregunta! Y en realidad tiene una gran historia en el mundo graphql .

Hubo múltiples problemas, discusiones y solicitudes de graphql-js en el graphql-js que intentaron discutir la posible sintaxis de esto, ya que era algo que muchos miembros de la comunidad consideraban necesario. Gracias a Lee Byron y esta solicitud de extracción , podemos agregar descripciones a un lenguaje de esquema mediante el uso de comentarios tradicionales.

Por ejemplo,

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

Y, si estamos usando graphql que es más nuevo que 0.7.0 , los comentarios se convierten en la descripción de los campos o tipos. Podemos verificar esto ejecutando una consulta de introspección en nuestro esquema:

const query = `
{
__schema {
types {
name
description,
fields {
name
description
}
}
}
}
`;
graphql(schema, query)
.then((result) => console.log(result));

Lo que nos daría un resultado que se parece a:

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

Y nos muestra que los # comentarios se incorporaron como descripciones de los campos / comentarios en los que los pusimos.

¡Espero que ayude!

Answer 2

En caso de que estés usando una implementación de Java ...

Para la versión 7.0 de graphql-java (la última versión en el momento de escribir este artículo) con un enfoque de esquema primero, puede usar comentarios sobre el campo, el tipo o el argumento.

Los literales de cadena no son sintaxis válida a partir de la versión 7.0.

Answer 3

Si está utilizando GraphQL.js versión 0.7.0 o superior, simplemente puede agregar un comentario directamente antes del campo, tipo o argumento que desea describir. Por ejemplo:

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

Debajo de la versión 0.7.0 no es posible agregar descripciones dentro del lenguaje del esquema.

ACTUALIZACIÓN: desde la versión v0.12.3 debe usar literales de cadena

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