Introspection-JSON

GraphQL SDL

Hvad er Introspection-JSON til SDL Konverteren?

Når du henter et schema fra Apollo Studio, Postman, Insomnia eller kører get-graphql-schema mod et live-endpoint, er det ikke det venlige SDL, du selv skrev, der kommer tilbage — det er resultatet af query { __schema { ... } }: 600+ linjer indlejret JSON, der beskriver hver type, hvert felt og hver modifier i et træ af kind- / name- / ofType-objekter. Brugbart for et værktøj, ulæseligt for et menneske. Denne konverter tager den JSON og skriver den ud igen som det SDL, du rent faktisk ville committe til et repo, efter introspection-reglerne i GraphQL-specifikationen fra oktober 2021.

Det hele sker i din browser — ingen upload, ingen AI, intet schema sendes nogen steder. Konverteringslogikken spejler det, graphql-js laver internt med buildClientSchema og printSchema: går igennem __schema-træet, springer de introspection-specifikke typer (__Schema, __Type, __Field, …) og indbyggede skalarer over og udskriver hver tilbageværende definition med beskrivelse, felter, argumenter, defaultværdier og deprecation-grunde i behold. Uanset om du indsætter hele kuverten { "data": { "__schema": ... } }, kun { "__schema": ... } eller bare den nøgne __schema-værdi — siden klarer alle tre.

Outputtet er grupperet: først skalarer, så enum's, interfaces, unions, input-typer og til sidst objekt-typer — alfabetisk inden for hver gruppe, med to mellemrums indrykning og en tom linje mellem definitioner. Idempotent nok til at smide direkte ind i en <code>.graphql</code>-fil i dit repo.

Sådan bruger du konverteren

Tre trin. Knapperne nedenfor er de rigtige knapper på denne side.

Indsæt, upload eller hent et eksempel

Indsæt din introspection-JSON i venstre Input-panel — konverteringen sker automatisk en brøkdel af et sekund efter, du holder op med at skrive, så der er ingen Convert-knap at lede efter. Klik Upload for en .json-fil, du har eksporteret fra Apollo Studio eller Postman, eller tryk Eksempel for at hente et realistisk Order/Customer/Money introspection-resultat. En typisk indsætning starter sådan her:

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

Du kan også indsætte den indre { "__schema": ... }-værdi eller det nøgne __schema-objekt — siden prøver alle tre former. Værktøjer som get-graphql-schema og Apollo Servers introspection-endpoint producerer som standard én af disse former.

Læs SDL-outputtet

Det højre Output-panel renderer schemaet som SDL. Hver type står i sin egen definition med to mellemrums indrykning, felter ét pr. linje, beskrivelser bevares oven over typen eller feltet som block-strenge med tre citationstegn, og deprecation-grunde renderes som @deprecated(reason: "...") på samme linje. Indbyggede skalarer og __-introspection-typer filtreres fra — det du får, er præcis det schema, din server publicerer, på den måde Relays GraphQL-specifikation anbefaler at dokumentere det. Hvis JSON'en er ødelagt eller mangler __schema-feltet, får du en venlig inline-meddelelse i stedet for en stack trace.

Kopiér eller download

Tryk Kopiér for at få SDL'en med over i en PR-beskrivelse, et doc eller en chat. Tryk Download for at gemme det som schema.graphql — smid det direkte i dit repo. Ryd-knappen i input-panelet sætter dig tilbage til en tom tilstand. Konverteringen er helt klient-side; introspection-resultatet forlader aldrig siden.

Hvornår du faktisk ville bruge det her

Fang et schema fra et live-endpoint

Du arver en GraphQL-tjeneste, der ikke har en schema-fil i repo'et — kun den kørende server. Affyr en introspection-query, indsæt JSON'en her og du har en første schema.graphql committet på fem minutter. Lettere end at koble buildClientSchema og printSchema sammen fra graphql-js bare for at gøre det en enkelt gang.

Læs en Apollo Studio- eller Postman-eksport

Schema-eksporten fra Apollo Studio er introspection-JSON. Det samme gælder Postmans "Save schema"-knap på en GraphQL-request. Konvertér det her, og du kan faktisk skimme schemaet i en kode-editor i stedet for at knibe øjnene sammen til JSON.

Diff to snapshots af et live-schema

Kør introspection mod staging og produktion, konvertér hver til SDL og diff de to filer. At opdage et manglende felt eller en omdøbt enum-værdi er trivielt i SDL og praktisk taget umuligt i rå introspection-JSON.

Generér type-stubs fra en tjeneste, der ikke er din

Brug for TypeScript-typer eller React-hooks til en tredjeparts GraphQL-API? De fleste kodegeneratorer vil have SDL, ikke introspection-JSON. Konvertér her, og fodr så SDL'en ind i din codegen-pipeline — graphql-react, graphql-codegen eller hvad din stack nu bruger.

Almindelige spørgsmål

Kræver det hele kuverten { "data": { "__schema": ... } }?

Nej. Siden tager imod tre former: det fulde GraphQL-svarkuvert, kun { "__schema": ... } eller bare det nøgne __schema-objekt. Hvilken end du indsætter, finder den __schema-roden og arbejder derfra.

Hvad nu hvis min JSON ikke har et __schema-felt?

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

Bevares beskrivelser og deprecation-grunde?

Ja. Type- og felt-beskrivelser udskrives som block-strenge med tre citationstegn oven over definitionen. Deprecate-de felter og enum-værdier får @deprecated(reason: "...") på samme linje. Det matcher outputtet fra printSchema i graphql-js.

Hvad med indbyggede skalarer og __-introspection-typerne?

Filtreret fra. String, Int, Float, Boolean og ID er implicitte i SDL — de dukker kun op i felt-typer, ikke som top-level definitioner. Det samme gælder for __Schema, __Type, __Field og resten af introspection-meta-typerne.

Er outputtet garanteret round-trip tilbage til det samme introspection-resultat?

Semantisk, ja — SDL'en beskriver det samme schema. Byte for byte, nej, fordi rækkefølgen af typer og felter kan afvige fra din oprindelige kildefil. Outputtet alfabetiseres inden for hver gruppe af definitioner for stabile diffs.

Bliver mit introspection-resultat sendt til en server?

Nej. Konverteringen kører helt i din browser. Intet uploades, intet logges. Trygt at indsætte schemaer fra interne eller ikke-frigivne tjenester.

Andre GraphQL-værktøjer

Når du har SDL'en, klarer disse resten:

Introspection-JSON til GraphQL SDL