graphql / graphql/graphql.github.io
Documentation about adding a mutation was hard to follow
- 主要言語
- TypeScript
- スター
- 889
- フォーク
- 1.5k
- 平均マージ
- 4日 12時間
- マージ済み PR(30日)
- 21
説明
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)
コントリビューションガイド
調査の方向性
まず graphql.org/learn/queries/#mutations と graphql.org/learn/schema/#the-query-and-mutation-types の mutations セクションを比較します。どの例がクエリ言語で、どの例がスキーマ言語なのかを明確にし、Create User mutation に必要な変更を示すスキーマ例を追加します。読者が両者を区別し、混乱せずにスキーマ定義を見つけられれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- graphql
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 2/5
- 見積もり時間
- 1〜3時間
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 35/100