graphql / graphql/graphql.github.io

Clarification on "Schemas and Types" documentation

Aperta
#1,531 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
TypeScript
Stelle
889
Fork
1.5k
Merge medio
4g 12h
PR unite (30g)
21

Descrizione

Hoping my input from a GraphQL newbie reading your documentation is helpful. This section https://graphql.org/learn/schema/#the-query-and-mutation-types needs a more verbose explanation. It's not clear why I would define the Query and Mutation types in my own schema if they are already reserved entities in GraphQL. Are you suggesting that 'query' and 'mutation' are example entities or example types "Query" and "Mutation"? If so, I'd recommend prepending "my" to them to make this obvious. If not examples, why are they being defined? Can a schema have only one Query and one Mutation? It's confusing to someone new to GraphQL and I think some more verbose explanation and better example would be useful.

Also in this page, it seems like a bad idea to define an enumeration like Episode, of which the content is dynamic data. A better enumeration example would be something where the data items are expected to never change. E.g. Units = Kilometers | Miles

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia dalla sezione collegata «Schemas and Types» all’indirizzo graphql.org/learn/schema/#the-query-and-mutation-types e rivedi i suoi esempi di Query, Mutation ed Episode. Chiarisci se Query e Mutation sono tipi di schema di esempio o entità riservate, spiega i loro vincoli e sostituisci o rivedi l’esempio di enum dinamico in modo che la documentazione sia comprensibile per chi è alle prime armi con GraphQL.

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
45/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.