Input

Output

Hvad er GraphQL-fremviseren?

Hvis du nogensinde har indsat et stykke GraphQL SDL, der kom tilbage på én linje, og forsøgt at læse det, kender du problemet. Typer, felter, argumenter, direktiver og unionsmedlemmer klumper sig sammen, og strukturen forsvinder. Det her værktøj retter det. Indsæt dit schema i venstre panel, og højre panel renderer det med to-mellemrums indrykning, ét felt pr. linje, argumenter inline og block-string-beskrivelser holdt over den type eller det felt, de dokumenterer.

Pretty-printeren er håndskreven — ingen graphql npm-pakke indlæses på siden, så første render forbliver lille. Den tokeniserer SDL'en, går gennem klammestrukturen og udskriver den igen med konsistent spacing efter GraphQL-specifikationen fra oktober 2021. Den håndterer enhver SDL-konstruktion, man faktisk støder på: type, interface, union, enum, input, scalar, extend, schema, liste- og non-null-modifikatorer ([Foo!]!), default-værdier, direktiver og beskrivelser med tredobbelte anførselstegn. Allerede pænt formateret input kommer tilbage uændret.

Alt kører i din browser. Ingen upload, intet schema gemt nogen steder. Indsæt, læs, kopiér.

Sådan bruger du GraphQL-fremviseren

Tre hurtige trin. Knapperne beskrevet nedenfor er de faktiske knapper på denne side.

Indsæt, upload eller indlæs et eksempel

Indsæt et GraphQL-schema i det venstre Input-panel. Klik Upload for en .graphql-, .graphqls- eller .gql-fil, eller tryk Eksempel for at indlæse et realistisk e-handels-schema. Hurtigt eksempel på, hvordan minificeret SDL ser ud:

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 server-stil schemaer (med extend type Query) og selvstændige typedefinitioner virker. De accepterede former matcher det, værktøjer som Apollo Server parser.

Læs det formaterede output

Det højre Output-panel renderer den parsede SDL med to-mellemrums indrykning. Hvert felt, hver enum-værdi og hvert unionsmedlem får sin egen linje. Argumenter forbliver inline på feltlinjen, så signaturer læses naturligt. Beskrivelser skrevet som block-strings ("""...""") holdes over den type eller det felt, de beskriver, hvilket er måden, som Relays GraphQL-specifikation anbefaler at dokumentere et schema på. Hvis SDL'en har ubalancerede klammer eller andre parse-fejl, viser fremviseren en venlig besked i stedet for at crashe.

Kopiér eller download

Tryk Kopiér for at tage det formaterede schema med til en pull request, doc eller chat. Tryk Download for at gemme som .graphql. Ryd-knappen på input-panelet sætter dig tilbage til tom tilstand. Parsing foregår helt på klientsiden — dit schema forlader aldrig siden.

Hvornår du faktisk bruger det her

Reviews af schema-pull-requests

Reviewer en schema-PR, og diffen er svær at læse, fordi filen er kørt gennem en kodegenerator, der har fjernet formateringen? Indsæt den nye version her, skim strukturen, og gå så tilbage til diffen med en klarere mental model af, hvad der er ændret. Særligt nyttigt når teamet itererer på, hvad der tæller som godt schema-design.

Debugging af federation og subgraphs

Debugger en Apollo federation-gateway, og det sammensatte supergraph-schema kommer tilbage som én kæmpe klump? Indsæt den mergede SDL, find typen, der opfører sig forkert, se hvilken subgraph der bidrog med hvilket felt. De federation-direktiver, der dukker op i outputtet, vises sammen med resten af schemasyntaksen.

Dokumentere et API

Skriver offentlig dokumentation for et GraphQL-API, dit team ejer? Smid schemaet i fremviseren, kopiér den formaterede version til wikien eller README'en. Træstrukturen af typer, interfaces og unioner læses naturligt, når den er lagt ud med ét felt pr. linje.

Onboarding af nye ingeniører

En ny holdkammerat prøver at lære formen på jeres GraphQL-API. Et formateret schema med beskrivelser synlige over hver type er et meget mere venligt udgangspunkt end den uformaterede klump fra codegen-outputtet.

Almindelige spørgsmål

Validerer det mit schema, eller formaterer det bare?

Det formaterer kun. Fremviseren tjekker klamme- og anførselstegns-balance nok til at kunne pretty-printe, men verificerer ikke, at Query findes, at refererede typer er defineret, eller at direktivargumenter matcher deres definitioner. For fuld validering, brug reference-implementationen graphql-js eller kør det gennem din servers startup-checks.

Bliver mit schema sendt til en server?

Nej. Pretty-printeren kører helt i din browser. Intet uploades, intet logges. Sikkert at indsætte interne eller ikke-udgivne schemaer.

Håndterer det block-string-beskrivelser?

Ja. Beskrivelser med tredobbelte anførselstegn ("""En ordre afgivet af en kunde.""") bevares og udskrives på linjen over den type eller det felt, de dokumenterer. Det er den kanoniske måde at skrive SDL-dokumentation på ifølge GraphQL-specifikationen.

Hvad med direktiver og custom scalars?

Begge bevares. @deprecated, @key og enhver custom direktiv forbliver inline på feltet. Custom scalars som scalar DateTime udskrives på deres egen linje. Fremviseren forsøger ikke at fortolke direktivsemantik — det er op til din server.

Bliver allerede formateret SDL re-formateret?

Det er idempotent — at pretty-printe allerede pænt formateret SDL giver samme output. Så du kan køre fremviseren i et CI-check eller i et indsæt-og-sammenlign-workflow uden at bekymre dig om whitespace-drift.

Hvor stort et schema kan jeg indsætte?

Alt, hvad din browser kan rendere komfortabelt. Schemaer med et par hundrede typer er ikke noget problem. Over 5 MB begynder Ace-editoren selv at blive langsom — det er flaskehalsen, ikke parseren.

Andre GraphQL-værktøjer

At se er én del af at arbejde med GraphQL. Disse værktøjer tager sig af resten: