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!

}