JSON di introspection

GraphQL SDL

Che cos'è il convertitore JSON di introspection a SDL?

Quando peschi uno schema da Apollo Studio, Postman, Insomnia, o lanci get-graphql-schema contro un endpoint live, quello che torna indietro non è l'SDL amichevole che hai scritto — è il risultato di query { __schema { ... } }: 600+ righe di JSON annidato che descrivono ogni tipo, ogni campo e ogni modificatore in un albero di oggetti kind / name / ofType. Utile a uno strumento, illeggibile per un essere umano. Questo convertitore prende quel JSON e lo stampa di nuovo come l'SDL che committeresti davvero in un repo, seguendo le regole di introspection della spec GraphQL di ottobre 2021.

Tutto avviene nel tuo browser — niente upload, niente IA, nessuno schema spedito da nessuna parte. La logica di conversione rispecchia ciò che graphql-js fa internamente con buildClientSchema e printSchema: percorrere l'albero __schema, saltare i tipi riservati all'introspection (__Schema, __Type, __Field, …) e gli scalari built-in, ed emettere ogni definizione rimanente con descrizione, campi, argomenti, valori di default e motivi di deprecation intatti. Che tu incolli l'envelope completo { "data": { "__schema": ... } }, solo { "__schema": ... }, o anche il valore __schema nudo, la pagina gestisce tutte e tre le forme.

L'output è raggruppato: prima gli scalari, poi enum, interface, union, tipi di input e infine i tipi object — alfabetico dentro ogni gruppo, indentazione di due spazi e una riga vuota tra le definizioni. Idempotente abbastanza da finire dritto in un file <code>.graphql</code> del tuo repo.

Come usare il convertitore

Tre passi. I bottoni qui sotto sono i bottoni veri di questa pagina.

Incolla, carica o apri un esempio

Incolla il tuo JSON di introspection nel pannello Input a sinistra — la conversione parte da sola una frazione di secondo dopo che smetti di scrivere, quindi non c'è nessun bottone Convert da cercare. Clicca Carica per un file .json esportato da Apollo Studio o Postman, o premi Esempio per caricare un risultato di introspection realistico Order/Customer/Money. Un incollaggio tipico parte così:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

Puoi anche incollare il valore interno { "__schema": ... } o l'oggetto __schema nudo — la pagina prova tutte e tre le forme. Strumenti come get-graphql-schema e l'endpoint di introspection di Apollo Server producono di default una di queste forme.

Leggi l'output SDL

Il pannello Output a destra renderizza lo schema come SDL. Ogni tipo è nella sua definizione con indentazione di due spazi, campi uno per riga, descrizioni mantenute sopra il tipo o il campo come stringhe a blocco con triple virgolette, e i motivi di deprecation renderizzati come @deprecated(reason: "..."). Gli scalari built-in e i tipi di introspection __ vengono filtrati — quello che ottieni è esattamente lo schema che il tuo server pubblica, nel modo in cui la spec GraphQL di Relay raccomanda di documentarlo. Se il JSON è malformato o manca il campo __schema, ottieni un messaggio inline amichevole invece di uno stack trace.

Copia o scarica

Premi Copia per portarti via l'SDL per la descrizione di una PR, un doc o una chat. Premi Scarica per salvarlo come schema.graphql — buttalo dritto nel tuo repo. Il bottone clear del pannello di input ti riporta allo stato vuoto. La conversione è completamente client-side; il risultato di introspection non lascia mai la pagina.

Quando lo useresti davvero

Catturare uno schema da un endpoint live

Erediti un servizio GraphQL che non ha un file di schema nel repo — solo il server in esecuzione. Lanci una query di introspection, incolli il JSON qui, e in cinque minuti hai un schema.graphql iniziale committato. Più semplice che cablare buildClientSchema e printSchema da graphql-js solo per farlo una volta.

Leggere un export di Apollo Studio o Postman

L'export di schema da Apollo Studio è il JSON di introspection. Stessa cosa per il bottone "Save schema" di Postman su una request GraphQL. Convertilo qui e potrai davvero scorrere lo schema in un editor di codice invece di strizzare gli occhi guardando il JSON.

Diff tra due snapshot di uno schema live

Lancia introspection su staging e production, converti ognuno in SDL, e fai il diff dei due file. Beccare un campo mancante o un valore di enum rinominato è banale in SDL e praticamente impossibile in JSON di introspection grezzo.

Generare type stub da un servizio non tuo

Ti servono tipi TypeScript o React hooks per un'API GraphQL di terze parti? La maggior parte dei generatori di codice vuole SDL, non JSON di introspection. Convertilo qui, poi dai in pasto l'SDL alla tua pipeline di codegen — graphql-react, graphql-codegen, o quello che usa il tuo stack.

Domande frequenti

Serve l'envelope completo { "data": { "__schema": ... } }?

No. La pagina accetta tre forme: l'envelope completo della response GraphQL, solo { "__schema": ... }, o anche l'oggetto __schema nudo. Qualsiasi tu incolli, trova la radice __schema e lavora da lì.

E se il mio JSON non ha il campo __schema?

Ricevi un messaggio amichevole: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Niente crash, niente stack trace.

Descrizioni e motivi di deprecation vengono preservati?

Sì. Le descrizioni di tipo e campo vengono emesse come stringhe a blocco con triple virgolette sopra la definizione. Campi e valori di enum deprecati ottengono @deprecated(reason: "...") sulla stessa riga. Combacia con l'output di printSchema di graphql-js.

E gli scalari built-in e i tipi di introspection __?

Filtrati via. String, Int, Float, Boolean e ID sono impliciti in SDL — appaiono solo nei tipi dei campi, non come definizioni di livello superiore. Stessa cosa per __Schema, __Type, __Field e il resto dei meta-tipi di introspection.

L'output è garantito di tornare allo stesso risultato di introspection?

Semanticamente sì — l'SDL descrive lo stesso schema. Byte per byte no, perché l'ordine di tipi e campi può differire dal tuo file sorgente originale. L'output è ordinato alfabeticamente dentro ogni gruppo di definizioni per diff stabili.

Il mio risultato di introspection viene mandato a un server?

No. La conversione gira interamente nel tuo browser. Niente viene caricato, niente viene loggato. Tranquillo a incollare schemi di servizi interni o non ancora rilasciati.

Altri strumenti GraphQL

Una volta che hai l'SDL, questi gestiscono il resto:

JSON di introspection a GraphQL SDL