graphql / graphql/graphql.github.io
Documentation about adding a mutation was hard to follow
- Lenguaje dominante
- TypeScript
- Estrellas
- 889
- Forks
- 1.5k
- Merge medio
- 4 d 12 h
- PR fusionados (30 d)
- 21
Descripción
I was looking into how to add a "Create User" mutation to my graphql-js server. It took me a while to end up at the right code, so just documenting where I got confused:
1. Searched for "Mutation" on the site. There are two sections ostensibly about mutation:
a. http://graphql.org/learn/queries/#mutations
b. http://graphql.org/learn/schema/#the-query-and-mutation-types
1. Skimming each page, it was hard to figure out how to actually define a mutation in the schema. The code talking about mutations wasn't clear if it was showing how to do them in the query or in the schema.
1. I found the operative sentence is in (b): "Mutations work in a similar way - you define fields on the Mutation type, and those are available as the root mutation fields you can call in your query." and was able to write the correct schema:
```
input CreatePersonInput {
name: String
}
type Mutation {
createPerson(person: CreatePersonInput!): Person
}
```
Suggestions:
- I was thinking it would be better to just put an example of the schema changes necessary to make a mutation right into the schema (b) section to avoid confusion
- Make it clearer when a block of code in the docs is in GraphQL query language or schema language (maybe even show "Query" and "Response" labels next to the left and right sides)
Guía de contribución
Línea de trabajo
Comienza comparando las secciones sobre mutations en graphql.org/learn/queries/#mutations y graphql.org/learn/schema/#the-query-and-mutation-types. Aclara qué ejemplos corresponden al lenguaje de consultas y cuáles al lenguaje de esquemas, y añade un ejemplo de esquema que muestre los cambios necesarios para una mutation Create User. Se considerará terminado cuando un lector pueda distinguir ambos y encontrar la definición del esquema sin confusión.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- graphql
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 2/5
- Tiempo estimado
- 1-3 horas
- Estado de actividad
- Estancado
- Claridad
- Bastante claro
- Aptitud para principiantes
- 35/100