graphql / graphql/graphql.github.io
Documentation about adding a mutation was hard to follow
- Lingua principale
- TypeScript
- Stelle
- 889
- Fork
- 1.5k
- Merge medio
- 4g 12h
- PR unite (30g)
- 21
Descrizione
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)
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Start by comparing the mutations sections at graphql.org/learn/queries/#mutations and graphql.org/learn/schema/#the-query-and-mutation-types. Clarify which examples are query language versus schema language, and add a schema example showing the changes needed for a Create User mutation. Done means a reader can distinguish the two and find the schema definition without confusion.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- graphql
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 2/5
- Tempo stimato
- 1-3 ore
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100