Generator för JSON svarsscheman till OpenAPI
Härled ett svarsschema från JSON exempel och skapa en OpenAPI 3.0.3 YAML sökväg.
Så fungerar det
Klistra in ett JSON svarsexempel, ange en bokstavlig sökväg och välj GET, POST, PUT eller DELETE. Generatorn härleder ett schema för svarskroppen och lägger det i ett OpenAPI 3.0.3 YAML dokument.
Använd representativa exempel för att visa möjliga variationer i svaret. När flera objekt förekommer på samma arrayplats kombinerar generatorn deras egenskaper och markerar en egenskap som obligatorisk endast om varje observerat objekt innehåller den.
Granska de härledda typerna och obligatoriska fälten innan du använder YAML. Lägg själv till anropskroppar, parametrar, autentisering, felsvar och eventuella sökvägsparametrar. Validera sedan hela dokumentet med en OpenAPI validator.
Använd verktyget när du har JSON exempel men saknar ett svarsschema. Det dokumenterar bara vald sökväg och metod utifrån det angivna exemplet.
Steg för steg
- Klistra in ett JSON svarsexempel
- Ange en bokstavlig sökväg och välj metod
- Granska och kopiera svarsschemat
Genomräknat exempel
För GET /api/users klistrar du in {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. Exemplet innehåller nästlade objekt, blandade värden i en array och två mätobjekt.
Resultatet markerar user, tags och metrics som obligatoriska. Båda mätobjekten innehåller count, så även det fältet är obligatoriskt där. score och active förekommer bara i ett objekt var och är därför valfria. tags godtar en sträng eller ett heltal. Båda observerade typerna är nullable eftersom exemplet också innehåller null.
När verktyget passar
Använd generatorn för att omvandla JSON svarskroppar från exempel till ett första OpenAPI svarsschema när du dokumenterar en sökväg.
Verktyget ordnar observerade svarsformer. Det skapade dokumentet behöver fortfarande uppgifter om anrop, säkerhet, fel och parametrar för ditt API.
Vanliga misstag
Ett enda objekt gör att alla inkluderade egenskaper verkar obligatoriska. Ange flera representativa objekt på samma arrayplats för att hitta egenskaper som varierar mellan svar.
Behandla inte härlett resultat som en fullständig API definition. Kontrollera hantering av null, valfria fält, arrayvarianter och bokstavliga sökvägar. Lägg till anrops och feldetaljer som ligger utanför verktygets omfattning.
Regler för härledning
För varje objektplats gäller: obligatoriska nycklar = nycklar som finns i alla observerade objekt.
För varje värde gäller: härlett schema = föreningen av observerade typer utom null.
När null observeras med en känd typ markeras det typade schemat som nullable.
Härledningen utgår från exempel och kontrollerar inte ett kontrakt vid körning. Ett exempel visar inte vilka fält som kan saknas i produktionssvar.
Begränsningar och antaganden
Resultatet beskriver observerade exempelvärden. Det kan inte hitta fält som saknas i alla exempel, bevisa att ett fält är valfritt i produktion eller härleda elementtypen från en tom array. Ett värde som bara är null har ingen härledbar typ. Blandade värden visas som alternativ och kan behöva jämföras med API kontraktet.
Viktiga termer
- OpenAPI dokument
- Ett OpenAPI dokument beskriver en API:s sökvägar, operationer, indata, svar och andra detaljer i ett maskinläsbart format.
- Schema
- Ett schema beskriver datas förväntade struktur och värdetyper, till exempel ett objekt med namngivna egenskaper.
- Obligatorisk egenskap
- I det här resultatet betyder obligatorisk att egenskapen fanns i varje observerat objekt på den platsen. Det bevisar inte beteendet i produktion.
Jämför relaterade verktyg
Använd omvandlaren från YAML till JSON för att få JSON från indata med YAML som stöds. Använd SQL till TypeScript för TypeScript typer från en tabellbeskrivning. Det här verktyget härleder ett svarsschema från JSON exempel.
Generatorn för simulerade API data skapar rader från ett JSON exempelobjekt. Det här verktyget härleder ett svarsschema från ett JSON exempel och skapar inte simulerade data.
FAQ
Hur blir exemplet ett svarsschema?
Generatorn granskar alla värden i JSON exemplet. Den skapar objektegenskaper, granskar alla arrayelement och kombinerar observerade typer med anyOf vid behov. Exemplet har strängar, null och ett heltal i tags arrayen. Därför godtar dess items schema en nullable sträng eller ett nullable heltal.
Hur visas null och olika typer?
Objekt blir scheman med egenskaper. En egenskap markeras som obligatorisk när den finns i varje observerat objekt på den platsen. Värden med olika observerade typer använder anyOf. Om null förekommer tillsammans med en annan typ får det typade schemat nullable: true. Ett värde som bara förekommer som null har ingen härledbar typ och schemat lämnas utan begränsning.
Vad ingår i det skapade dokumentet?
Dokumentet innehåller en sökväg, den valda metoden GET, POST, PUT eller DELETE och ett lyckat JSON svar med status 200. Schemat lagras under components och hänvisas från svaret. Generatorn skapar inte någon request body, parametrar, säkerhetsregler, felsvar eller headers.
Kan jag ange en sökvägsparameter som ett ID?
Sökvägen måste vara bokstavlig och börja med ett snedstreck, till exempel /api/users. Sökvägar med klammerparenteser avvisas eftersom en mall som /api/users/{id} också behöver en deklarerad sökvägsparameter som generatorn inte lägger till.
Skapar eller validerar verktyget ett fullständigt API kontrakt?
Nej. Resultatet beskriver svarskroppen från ett exempel. Det härleder inte scheman för anrop och validerar inte YAML mot OpenAPI specifikationen. Lägg till övriga operationer och svarsdetaljer själv och kontrollera sedan hela dokumentet med en OpenAPI validator.
Relaterade verktyg
Omvandlaren från YAML till JSON omvandlar indata med YAML som stöds till JSON. SQL till TypeScript härleder typdeklarationer från SQL strukturer. Generatorn för simulerade API data skapar rader från ett JSON exempelobjekt. Det här verktyget härleder ett svarsschema från JSON exempel.