Introspection-JSON

GraphQL SDL

Vad är Introspection-JSON till SDL-konverteraren?

När du drar ut ett schema från Apollo Studio, Postman, Insomnia eller kör get-graphql-schema mot en live-endpoint är det inte den trevliga SDL:n du själv skrev som kommer tillbaka — det är resultatet av query { __schema { ... } }: 600+ rader nästlad JSON som beskriver varje typ, varje fält och varje modifierare i ett träd av kind- / name- / ofType-objekt. Användbart för ett verktyg, oläsligt för en människa. Den här konverteraren tar den JSON:en och skriver ut den som den SDL du faktiskt skulle committa till ett repo, enligt introspection-reglerna i GraphQL-specen från oktober 2021.

Allt sker i din webbläsare — ingen uppladdning, ingen AI, inget schema skickas någonstans. Konverteringslogiken speglar det graphql-js gör internt med buildClientSchema och printSchema: vandra genom __schema-trädet, hoppa över de introspection-specifika typerna (__Schema, __Type, __Field, …) och inbyggda skalärerna, och skriva ut varje kvarvarande definition med dess beskrivning, fält, argument, defaultvärden och deprecation-skäl intakta. Oavsett om du klistrar in hela kuvertet { "data": { "__schema": ... } }, bara { "__schema": ... } eller till och med det blottade __schema-värdet — sidan klarar alla tre.

Utdata grupperas: först skalärerna, sedan enum:s, interfaces, unions, input-typer och sist objekt-typer — alfabetiskt inom varje grupp, med två blanksteg i indrag och en blankrad mellan definitioner. Idempotent nog att släppas rakt in i en <code>.graphql</code>-fil i ditt repo.

Så använder du konverteraren

Tre steg. Knapparna nedan är de riktiga knapparna på den här sidan.

Klistra in, ladda upp eller hämta ett exempel

Klistra in din introspection-JSON i den vänstra Indata-panelen — konverteringen sker automatiskt en bråkdels sekund efter att du slutar skriva, så det finns ingen Convert-knapp att jaga. Klicka Ladda upp för en .json-fil du exporterat från Apollo Studio eller Postman, eller tryck Exempel för att läsa in ett realistiskt Order/Customer/Money-introspection-resultat. Ett typiskt inklistrande börjar så här:

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

Du kan också klistra in det inre { "__schema": ... }-värdet eller det blottade __schema-objektet — sidan provar alla tre formerna. Verktyg som get-graphql-schema och Apollo Servers introspection-endpoint producerar en av dessa former som standard.

Läs SDL-utdata

Den högra Utdata-panelen renderar schemat som SDL. Varje typ får sin egen definition med två blanksteg i indrag, fält ett per rad, beskrivningar ovanför typen eller fältet som block-strängar med tre citattecken, och deprecation-skäl renderas som @deprecated(reason: "...") på samma rad. Inbyggda skalärer och __-introspection-typer filtreras bort — det du får är exakt det schema som din server publicerar, på det sätt Relays GraphQL-spec rekommenderar att man dokumenterar det. Om JSON:en är trasig eller saknar __schema-fältet får du ett vänligt inline-meddelande i stället för en stack trace.

Kopiera eller ladda ner

Tryck Kopiera för att ta med dig SDL:t till en PR-beskrivning, ett dokument eller en chatt. Tryck Ladda ner för att spara som schema.graphql — släpp det rakt in i ditt repo. Rensa-knappen i indata-panelen återställer dig till tomt läge. Konverteringen är helt klient-sida; introspection-resultatet lämnar aldrig sidan.

När du faktiskt skulle använda det här

Fånga ett schema från en live-endpoint

Du ärver en GraphQL-tjänst som inte har någon schemafil i repo:t — bara den körande servern. Skjut iväg en introspection-query, klistra in JSON:en här och du har en första schema.graphql committad på fem minuter. Lättare än att koppla ihop buildClientSchema och printSchema från graphql-js bara för att göra det en enda gång.

Läs en Apollo Studio- eller Postman-export

Schemaexporten från Apollo Studio är introspection-JSON. Detsamma för Postmans "Save schema"-knapp på en GraphQL-request. Konvertera här och du kan faktiskt skumma schemat i en kod-editor i stället för att kisa på JSON.

Diffa två snapshots av ett live-schema

Kör introspection mot staging och produktion, konvertera vardera till SDL och diffa de två filerna. Att hitta ett saknat fält eller ett omdöpt enum-värde är trivialt i SDL och i princip omöjligt i rå introspection-JSON.

Generera typ-stubbar från en tjänst du inte äger

Behöver du TypeScript-typer eller React-hooks för en tredjeparts GraphQL-API? De flesta kodgeneratorer vill ha SDL, inte introspection-JSON. Konvertera här och mata sedan in SDL:t i din codegen-pipeline — graphql-react, graphql-codegen eller vad nu din stack använder.

Vanliga frågor

Krävs hela kuvertet { "data": { "__schema": ... } }?

Nej. Sidan tar emot tre former: hela GraphQL-svarskuvertet, bara { "__schema": ... } eller till och med det blottade __schema-objektet. Vilken du än klistrar in hittar den __schema-roten och jobbar därifrån.

Vad händer om min JSON saknar __schema-fält?

Du får ett vänligt meddelande: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Ingen krasch, ingen stack trace.

Bevaras beskrivningar och deprecation-skäl?

Ja. Typ- och fältbeskrivningar skrivs ut som block-strängar med tre citattecken ovanför definitionen. Deprecate:ade fält och enum-värden får @deprecated(reason: "...") på samma rad. Detta motsvarar utdata från printSchema i graphql-js.

Hur blir det med inbyggda skalärer och __-introspection-typer?

Bortfiltrerade. String, Int, Float, Boolean och ID är implicita i SDL — de dyker bara upp i fälttyper, inte som definitioner på toppnivå. Detsamma för __Schema, __Type, __Field och resten av introspection-meta-typerna.

Är utdata garanterat round-trip-bar tillbaka till samma introspection-resultat?

Semantiskt, ja — SDL:t beskriver samma schema. Byte för byte, nej, eftersom ordningen på typer och fält kan skilja sig från din ursprungliga källfil. Utdata är alfabetiserad inom varje grupp av definitioner för stabila diffar.

Skickas mitt introspection-resultat till en server?

Nej. Konverteringen körs helt i din webbläsare. Inget laddas upp, inget loggas. Säkert att klistra in scheman från interna eller ej släppta tjänster.

Andra GraphQL-verktyg

När du har SDL:t tar de här hand om resten:

Introspection-JSON till GraphQL SDL