Introspection-JSON

GraphQL SDL

Hva er Introspection-JSON til SDL Konverteren?

Når du henter et schema fra Apollo Studio, Postman, Insomnia eller kjører get-graphql-schema mot et live-endepunkt, er det ikke det vennlige SDL-et du selv skrev som kommer tilbake — det er resultatet av query { __schema { ... } }: 600+ linjer nøstet JSON som beskriver hver type, hvert felt og hver modifier i et tre av kind- / name- / ofType-objekter. Nyttig for et verktøy, uleselig for et menneske. Denne konverteren tar den JSON-en og skriver den ut som det SDL-et du faktisk ville committet til et repo, etter introspection-reglene i GraphQL-spesifikasjonen fra oktober 2021.

Alt skjer i nettleseren din — ingen opplasting, ingen AI, ingen schemaer sendes noe sted. Konverteringslogikken speiler det graphql-js gjør internt med buildClientSchema og printSchema: gå gjennom __schema-treet, hopp over de introspection-spesifikke typene (__Schema, __Type, __Field, …) og innebygde skalarer, og skriv ut hver gjenværende definisjon med beskrivelse, felter, argumenter, defaultverdier og deprecation-grunner intakte. Enten du limer inn hele konvolutten { "data": { "__schema": ... } }, bare { "__schema": ... } eller bare den nakne __schema-verdien — siden takler alle tre.

Utdataen er gruppert: først skalarer, så enum-er, interfaces, unions, input-typer og til slutt objekt-typer — alfabetisk innenfor hver gruppe, med to mellomroms innrykk og en blank linje mellom definisjoner. Idempotent nok til å slippes rett inn i en <code>.graphql</code>-fil i repo-et ditt.

Slik bruker du konverteren

Tre steg. Knappene nedenfor er de faktiske knappene på denne siden.

Lim inn, last opp eller hent et eksempel

Lim inn introspection-JSON-en din i venstre Input-panel — konverteringen skjer automatisk en brøkdel av et sekund etter at du slutter å skrive, så det er ingen Convert-knapp å lete etter. Klikk Last opp for en .json-fil du har eksportert fra Apollo Studio eller Postman, eller trykk Eksempel for å hente et realistisk Order/Customer/Money introspection-resultat. En typisk innliming starter slik:

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

Du kan også lime inn den indre { "__schema": ... }-verdien eller det nakne __schema-objektet — siden prøver alle tre formene. Verktøy som get-graphql-schema og Apollo Servers introspection-endepunkt produserer som standard én av disse formene.

Les SDL-utdataen

Det høyre Output-panelet rendrer schemaet som SDL. Hver type står i sin egen definisjon med to mellomroms innrykk, felter ett per linje, beskrivelser bevart over typen eller feltet som blokkstrenger med tre anførselstegn, og deprecation-grunner rendret som @deprecated(reason: "...") på samme linje. Innebygde skalarer og __-introspection-typer filtreres bort — det du får er nøyaktig det schemaet serveren din publiserer, slik Relays GraphQL-spesifikasjon anbefaler å dokumentere det. Hvis JSON-en er ødelagt eller mangler __schema-feltet, får du en vennlig inline-melding i stedet for en stack trace.

Kopier eller last ned

Trykk Kopier for å ta med deg SDL-et til en PR-beskrivelse, et doc eller en chat. Trykk Last ned for å lagre som schema.graphql — slipp det rett inn i repo-et ditt. Tøm-knappen i input-panelet setter deg tilbake til en blank tilstand. Konverteringen er fullt klient-side; introspection-resultatet forlater aldri siden.

Når du faktisk ville brukt dette

Fang et schema fra et live-endepunkt

Du arver en GraphQL-tjeneste som ikke har noen schema-fil i repo-et — bare den kjørende serveren. Skyt av en introspection-spørring, lim inn JSON-en her, og du har en første schema.graphql committet på fem minutter. Lettere enn å koble sammen buildClientSchema og printSchema fra graphql-js bare for å gjøre det én eneste gang.

Les en Apollo Studio- eller Postman-eksport

Schema-eksporten fra Apollo Studio er introspection-JSON. Det samme gjelder Postmans "Save schema"-knapp på en GraphQL-request. Konverter her, og du kan faktisk skumme schemaet i en kode-editor i stedet for å myse på JSON.

Diff to snapshots av et live-schema

Kjør introspection mot staging og produksjon, konverter hver til SDL og diff de to filene. Å oppdage et manglende felt eller en omdøpt enum-verdi er trivielt i SDL og praktisk talt umulig i rå introspection-JSON.

Generer type-stubber fra en tjeneste du ikke eier

Trenger du TypeScript-typer eller React-hooks for et tredjeparts GraphQL-API? De fleste kodegeneratorer vil ha SDL, ikke introspection-JSON. Konverter her, og mat så SDL-et inn i codegen-pipelinen din — graphql-react, graphql-codegen eller hva stacken din nå bruker.

Vanlige spørsmål

Krever det hele konvolutten { "data": { "__schema": ... } }?

Nei. Siden tar imot tre former: den fulle GraphQL-svarkonvolutten, bare { "__schema": ... } eller bare det nakne __schema-objektet. Uansett hvilken du limer inn, finner den __schema-roten og jobber derfra.

Hva om JSON-en min ikke har et __schema-felt?

Du får en vennlig melding: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Ingen krasj, ingen stack trace.

Bevares beskrivelser og deprecation-grunner?

Ja. Type- og feltbeskrivelser skrives ut som blokkstrenger med tre anførselstegn over definisjonen. Deprecate-de felter og enum-verdier får @deprecated(reason: "...") på samme linje. Dette matcher utdataen fra printSchema i graphql-js.

Hva med innebygde skalarer og __-introspection-typene?

Filtrert bort. String, Int, Float, Boolean og ID er implisitte i SDL — de dukker bare opp i felttyper, ikke som top-level-definisjoner. Det samme gjelder __Schema, __Type, __Field og resten av introspection-meta-typene.

Er utdataen garantert å round-trip-e tilbake til samme introspection-resultat?

Semantisk, ja — SDL-et beskriver samme schema. Byte for byte, nei, fordi rekkefølgen på typer og felter kan avvike fra din opprinnelige kildefil. Utdataen er alfabetisert innen hver gruppe av definisjoner for stabile differ.

Sendes introspection-resultatet mitt til en server?

Nei. Konverteringen kjører fullt og helt i nettleseren din. Ingenting lastes opp, ingenting logges. Trygt å lime inn schemaer fra interne eller ennå ikke utgitte tjenester.

Andre GraphQL-verktøy

Når du har SDL-et, tar disse seg av resten:

Introspection-JSON til GraphQL SDL