graphql / graphql/graphql.github.io
Documentation about adding a mutation was hard to follow
- Vorherrschende Sprache
- TypeScript
- Sterne
- 889
- Forks
- 1.5k
- Ø Merge
- 4 T. 12 Std.
- Gemergte PRs (30 T.)
- 21
Beschreibung
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)
Beitragsleitfaden
Rechercherichtung
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.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- graphql
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 2/5
- Geschätzter Aufwand
- 1-3 Stunden
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100