Inndata

Utdata

Hva er GraphQL-viseren?

Hvis du noen gang har limt inn en bit GraphQL SDL som kom tilbake på én linje og prøvd å lese det, kjenner du problemet. Typer, felter, argumenter, direktiver og unionsmedlemmer klumper seg sammen og strukturen forsvinner. Dette verktøyet fikser det. Lim inn schemaet ditt i venstre panel, så renderer høyre panel det med to-mellomroms innrykk, ett felt per linje, argumenter inline og block-string-beskrivelser holdt over typen eller feltet de dokumenterer.

Pretty-printeren er håndskrevet — ingen graphql npm-pakke lastes inn på siden, så første rendering holder seg lett. Den tokeniserer SDL-en, går gjennom klammestrukturen og skriver den ut igjen med konsistent spacing i tråd med GraphQL-spesifikasjonen fra oktober 2021. Den håndterer alle SDL-konstruksjoner du faktisk ser i praksis: type, interface, union, enum, input, scalar, extend, schema, liste- og non-null-modifikatorer ([Foo!]!), default-verdier, direktiver og beskrivelser med trippel-anførselstegn. Allerede pent formatert inndata kommer tilbake uendret.

Alt kjører i nettleseren din. Ingen opplasting, ingen schemaer lagret noe sted. Lim inn, les, kopier.

Slik bruker du GraphQL-viseren

Tre raske steg. Knappene beskrevet under er de faktiske knappene på denne siden.

Lim inn, last opp eller last et eksempel

Lim inn et GraphQL-schema i det venstre Inndata-panelet. Klikk Last opp for en .graphql-, .graphqls- eller .gql-fil, eller trykk Eksempel for å laste et realistisk netthandel-schema. Rask smakebit på hvordan minifisert SDL ser ut:

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

Både schemaer i serverstil (med extend type Query) og frittstående typedefinisjoner fungerer. Formene som aksepteres samsvarer med det verktøy som Apollo Server parser.

Les det formaterte utdataet

Det høyre Utdata-panelet renderer den parsede SDL-en med to-mellomroms innrykk. Hvert felt, hver enum-verdi og hvert unionsmedlem får sin egen linje. Argumenter forblir inline på feltlinjen, så signaturer leses naturlig. Beskrivelser skrevet som block-strings ("""...""") holdes over typen eller feltet de beskriver, som er måten Relays GraphQL-spesifikasjon anbefaler å dokumentere et schema på. Hvis SDL-en har ubalanserte klammer eller andre parsefeil, viser viseren en vennlig melding i stedet for å krasje.

Kopier eller last ned

Trykk Kopier for å ta med det formaterte schemaet til en pull request, doc eller chat. Trykk Last ned for å lagre som .graphql. Tøm-knappen på inndata-panelet setter deg tilbake til tom tilstand. Parsing skjer helt klient-side — schemaet ditt forlater aldri siden.

Når du faktisk bruker dette

Reviewer av schema-pull-requests

Reviewer en schema-PR, og diffen er vanskelig å lese fordi filen har gått gjennom en kodegenerator som har fjernet formateringen? Lim inn den nye versjonen her, skann strukturen med øyet, og gå så tilbake til diffen med en tydeligere mental modell av hva som er endret. Spesielt nyttig når teamet itererer på hva som teller som god schema-design.

Debugging av federation og subgraphs

Debugger en Apollo federation-gateway, og det sammensatte supergraph-schemaet kommer tilbake som én diger klump? Lim inn den mergede SDL-en, finn typen som oppfører seg feil, se hvilken subgraph som bidro med hvilket felt. Federation-direktivene som dukker opp i utdataet vises sammen med resten av schema-syntaksen.

Dokumentere et API

Skriver offentlig dokumentasjon for et GraphQL-API teamet ditt eier? Slipp schemaet i viseren, kopier den formaterte versjonen til wikien eller README-en. Trestrukturen av typer, interfaces og unions leses naturlig når den er lagt ut med ett felt per linje.

Onboarding av nye utviklere

En ny lagkamerat prøver å lære formen på GraphQL-APIet deres. Et formatert schema med beskrivelser synlige over hver type er et mye mer vennlig utgangspunkt enn den uformaterte klumpen fra codegen-utdataet.

Vanlige spørsmål

Validerer det schemaet mitt, eller formaterer det bare?

Bare formaterer. Viseren sjekker klamme- og anførselstegns-balanse nok til å kunne pretty-printe, men verifiserer ikke at Query finnes, at refererte typer er definert, eller at direktivargumenter samsvarer med definisjonene sine. For full validering, bruk referanseimplementasjonen graphql-js eller kjør det gjennom serverens startup-sjekker.

Blir schemaet mitt sendt til en server?

Nei. Pretty-printeren kjører helt i nettleseren din. Ingenting lastes opp, ingenting logges. Trygt å lime inn interne eller ikke-utgitte schemaer.

Håndterer det block-string-beskrivelser?

Ja. Beskrivelser med trippel-anførselstegn ("""En bestilling lagt inn av en kunde.""") bevares og skrives ut på linjen over typen eller feltet de dokumenterer. Det er den kanoniske måten å skrive SDL-dokumentasjon på ifølge GraphQL-spesifikasjonen.

Hva med direktiver og custom scalars?

Begge bevares. @deprecated, @key og ethvert custom direktiv forblir inline på feltet. Custom scalars som scalar DateTime skrives ut på sin egen linje. Viseren prøver ikke å tolke direktivsemantikk — det er opp til serveren din.

Blir allerede formatert SDL re-formatert?

Det er idempotent — å pretty-printe allerede pent formatert SDL gir samme utdata. Så du kan kjøre viseren i en CI-sjekk eller en lim-inn-og-sammenlign-arbeidsflyt uten å bekymre deg for whitespace-drift.

Hvor stort schema kan jeg lime inn?

Alt nettleseren din rendrer komfortabelt. Schemaer med noen hundre typer er ikke noe problem. Over 5 MB begynner Ace-editoren selv å bli treig — det er flaskehalsen, ikke parseren.

Andre GraphQL-verktøy

Å se er én del av å jobbe med GraphQL. Disse verktøyene tar seg av resten: