Input

Output

Cos'è il visualizzatore GraphQL?

Se hai mai incollato un pezzo di SDL GraphQL tornato indietro su una sola riga e hai provato a leggerlo, sai qual è il problema. Tipi, campi, argomenti, direttive e membri delle union si schiacciano tutti insieme e la struttura sparisce. Questo strumento sistema la cosa. Incolla lo schema nel pannello di sinistra e quello di destra lo renderizza con indentazione di due spazi, un campo per riga, argomenti inline e descrizioni in block-string mantenute sopra il tipo o il campo che documentano.

Il formattatore è scritto a mano — nessun pacchetto npm graphql viene caricato nella pagina, quindi il primo paint resta leggero. Tokenizza l'SDL, attraversa la struttura delle parentesi graffe e lo riemette con spaziatura coerente secondo la spec GraphQL di ottobre 2021. Gestisce ogni costrutto SDL che capita davvero: type, interface, union, enum, input, scalar, extend, schema, modificatori di lista e non-null ([Foo!]!), valori di default, direttive e descrizioni con triple virgolette. L'input già formattato torna identico.

Tutto gira nel tuo browser. Nessun upload, nessuno schema salvato da nessuna parte. Incolla, leggi, copia.

Come usare il visualizzatore GraphQL

Tre passaggi rapidi. I bottoni descritti sotto sono i bottoni veri di questa pagina.

Incolla, carica o usa un esempio

Incolla uno schema GraphQL nel pannello Input a sinistra. Clicca Carica per un file .graphql, .graphqls o .gql, oppure premi Esempio per caricare uno schema e-commerce realistico. Esempio rapido di come appare un SDL minificato:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]! total:Money! status:OrderStatus!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Funzionano sia gli schemi in stile server (con extend type Query) sia le definizioni di tipo isolate. Le forme accettate corrispondono a quello che strumenti come Apollo Server parsano.

Leggi l'output formattato

Il pannello Output a destra renderizza l'SDL parsato con indentazione di due spazi. Ogni campo, valore di enum e membro di union ha la sua riga. Gli argomenti restano inline sulla riga del campo, così le firme si leggono naturalmente. Le descrizioni scritte come block-string ("""...""") restano sopra il tipo o il campo che descrivono, che è il modo raccomandato dalla specifica GraphQL di Relay per documentare uno schema. Se l'SDL ha graffe sbilanciate o altri errori di parsing, il visualizzatore mostra un messaggio amichevole invece di crashare.

Copia o scarica

Premi Copia per portare via lo schema formattato per una pull request, una doc o una chat. Premi Scarica per salvarlo come .graphql. Il bottone clear sul pannello di input ti rimette in stato vuoto. Il parsing avviene tutto lato client — il tuo schema non lascia mai la pagina.

Quando lo userai davvero

Review di pull request di schema

Stai facendo review di un PR di schema e il diff è duro da leggere perché il file è passato per un code generator che ha fatto fuori la formattazione? Incolla qui la nuova versione, scorri la struttura con l'occhio, poi torna al diff con un modello mentale più chiaro di cosa è cambiato. Particolarmente utile quando il team sta iterando su cosa conti come un buon design di schema.

Debug di federazione e subgraph

Stai debuggando un gateway di federazione Apollo e lo schema supergraph composto torna come un blocco enorme? Incolla l'SDL fuso, trova il tipo che si comporta male, vedi quale subgraph ha contribuito quale campo. Le direttive di federazione che compaiono nell'output sono documentate insieme al resto della sintassi dello schema.

Documentare un'API

Stai scrivendo doc pubblica per un'API GraphQL del tuo team? Butta lo schema nel visualizzatore, copia la versione formattata nel wiki o nel README. La forma ad albero di tipi, interfacce e union si legge naturale una volta disposta con un campo per riga.

Onboarding di nuovi sviluppatori

Un nuovo collega di team sta provando a imparare la forma della tua API GraphQL. Uno schema formattato con le descrizioni visibili sopra ogni tipo è un punto di partenza molto più amichevole del blocco non formattato dell'output del codegen.

Domande comuni

Valida lo schema o solo lo formatta?

Solo formattazione. Il visualizzatore controlla il bilanciamento di graffe e virgolette quanto basta per il pretty-print, ma non verifica che Query esista, che i tipi referenziati siano definiti o che gli argomenti delle direttive corrispondano alla definizione. Per la validazione completa, usa l'implementazione di riferimento graphql-js o passalo per i check di startup del tuo server.

Il mio schema viene mandato a un server?

No. Il pretty-printer gira interamente nel tuo browser. Niente upload, niente log. Sicuro per incollare schemi interni o non rilasciati.

Gestisce le descrizioni in block-string?

Sì. Le descrizioni con triple virgolette ("""Un ordine effettuato da un cliente.""") sono preservate ed emesse sulla riga sopra il tipo o il campo che documentano. È il modo canonico di scrivere doc SDL secondo la spec GraphQL.

E le direttive e gli scalari custom?

Entrambi vengono mantenuti. @deprecated, @key e qualunque direttiva custom restano inline sul campo. Gli scalari custom come scalar DateTime vengono emessi su una riga propria. Il visualizzatore non prova a interpretare la semantica delle direttive — quello è compito del tuo server.

Un SDL già formattato viene riformattato?

È idempotente — fare pretty-print di un SDL già pulito produce lo stesso output. Quindi puoi mettere il visualizzatore in un check di CI o in un flusso paste-and-compare senza preoccuparti di drift di whitespace.

Quanto grande può essere uno schema da incollare?

Tutto quello che il tuo browser riesce a renderizzare comodamente. Schemi da qualche centinaio di tipi non sono un problema. Sopra i 5 MB l'editor Ace stesso inizia a rallentare — il collo di bottiglia è quello, non il parser.

Altri strumenti GraphQL

Visualizzare è una parte del lavoro con GraphQL. Questi strumenti coprono il resto:

Visualizzatore GraphQL