Generator voor JSON responseschema's naar OpenAPI
Leid een responseschema af uit JSON voorbeelden en maak één OpenAPI 3.0.3 YAML pad.
Werking
Plak een JSON antwoordvoorbeeld, voer een letterlijk eindpuntpad in en kies GET, POST, PUT of DELETE. De generator leidt een schema voor de antwoordbody af en zet dit in een OpenAPI 3.0.3 YAML document.
Gebruik representatieve voorbeelden voor de variaties die het antwoord kan bevatten. Als meerdere objecten op dezelfde arraylocatie staan, combineert de generator hun eigenschappen en markeert een eigenschap alleen als verplicht wanneer elk waargenomen object die bevat.
Controleer de afgeleide typen en verplichte velden voordat je het YAML gebruikt. Voeg request bodies, parameters, verificatie, foutantwoorden en eventuele padparameterdeclaraties zelf toe. Controleer daarna het volledige document met een OpenAPI validator.
Gebruik deze tool als er JSON voorbeelden zijn maar geen responseschema. Alleen het gekozen pad en de methode worden op basis van het opgegeven voorbeeld beschreven.
Stap voor stap
- Plak een JSON antwoordvoorbeeld
- Voer een letterlijk pad in en kies de methode
- Controleer en kopieer het responseschema
Uitgewerkt voorbeeld
Plak voor GET /api/users {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. Het voorbeeld bevat geneste objecten, gemengde arraywaarden en twee metriekobjecten.
De uitvoer markeert user, tags en metrics als verplicht. Beide metriekobjecten bevatten count, dus ook dat veld is daar verplicht. score en active komen elk in één object voor en zijn daarom optioneel. tags accepteert een tekenreeks of geheel getal. Beide waargenomen typen zijn nullable omdat het voorbeeld ook null bevat.
Wanneer gebruik je deze tool
Gebruik de generator om voorbeeld JSON antwoordbodies om te zetten naar een eerste OpenAPI responseschema voor de documentatie van een pad.
De tool ordent waargenomen antwoordvormen. Het gegenereerde document heeft nog details over verzoeken, beveiliging, fouten en parameters van je API nodig.
Veelgemaakte fouten
Bij één object lijken alle opgenomen eigenschappen verplicht. Geef meerdere representatieve objecten op dezelfde arraylocatie om eigenschappen te herkennen die per antwoord verschillen.
Zie de afgeleide uitvoer niet als een complete API definitie. Controleer null verwerking, optionele velden, arrayvarianten en letterlijke paden. Voeg request en foutdetails toe die buiten het bereik van deze tool vallen.
Afleidingsregels
Per objectlocatie geldt: verplichte sleutels = sleutels die in elk waargenomen object voorkomen.
Per waarde geldt: afgeleid schema = vereniging van waargenomen typen behalve null.
Als null samen met een bekend type voorkomt, krijgt dat getypeerde schema het kenmerk nullable.
Deze afleiding gebruikt voorbeelden en controleert geen contract tijdens uitvoering. Eén voorbeeld laat niet zien welke velden in productieantwoorden kunnen ontbreken.
Beperkingen en aannames
Het resultaat beschrijft waargenomen voorbeeldwaarden. Het kan geen velden herkennen die in alle voorbeelden ontbreken, bewijst niet dat een veld optioneel is in productie en leidt geen itemtype af uit een lege array. Een waarde die alleen null is heeft geen afleidbaar type. Gemengde waarden staan als alternatieven in het schema en moeten mogelijk met het API contract worden vergeleken.
Belangrijke termen
- OpenAPI document
- Een OpenAPI document beschrijft paden, bewerkingen, invoer, antwoorden en andere API details in een machineleesbaar formaat.
- Schema
- Een schema beschrijft de verwachte structuur en waardetypen van gegevens, zoals een object met benoemde eigenschappen.
- Verplichte eigenschap
- In deze uitvoer betekent verplicht dat de eigenschap in elk waargenomen object op die plek voorkwam. Dit bewijst geen productiegedrag.
Vergelijk verwante tools
Gebruik de YAML naar JSON omzetter om ondersteunde YAML invoer naar JSON om te zetten. Gebruik SQL naar TypeScript voor TypeScript typen uit een tabeldefinitie. Deze tool leidt een responseschema af uit JSON voorbeelden.
De generator voor nagebootste API gegevens maakt rijen op basis van een JSON voorbeeldobject. Deze tool leidt één responseschema af uit een JSON voorbeeld en maakt geen nagebootste gegevens.
FAQ
Hoe wordt het voorbeeld een responseschema?
De generator bekijkt elke waarde in het JSON voorbeeld. Hij maakt objecteigenschappen, onderzoekt alle arrayitems en combineert waargenomen typen indien nodig met anyOf. De tags array in het voorbeeld bevat tekenreeksen, null en een geheel getal. Het itemschema accepteert daarom een nullable tekenreeks of geheel getal.
Hoe worden null en verschillende typen weergegeven?
Objecten worden schema's met eigenschappen. Een eigenschap is verplicht wanneer die op die plek voorkomt in elk waargenomen object. Waarden met verschillende waargenomen typen gebruiken anyOf. Als null samen met een ander type voorkomt, krijgt het getypeerde schema nullable: true. Voor een waarde die alleen null is, kan geen type worden afgeleid en blijft het schema onbegrensd.
Wat bevat het gegenereerde document?
Het document bevat één pad, de gekozen methode GET, POST, PUT of DELETE en één geslaagd JSON antwoord met status 200. Het schema staat onder components en wordt vanuit het antwoord aangehaald. De generator maakt geen request body, parameters, beveiligingsregels, foutantwoorden of headers.
Kan ik een padparameter invoeren, zoals een ID?
Het pad moet letterlijk zijn en met een schuine streep beginnen, zoals /api/users. Paden met accolades worden geweigerd, want een sjabloon zoals /api/users/{id} vereist ook een gedeclareerde padparameter die deze generator niet toevoegt.
Maakt of controleert dit een volledig API contract?
Nee. De uitvoer beschrijft de antwoordbody van een voorbeeld. De tool leidt geen requestschema's af en controleert het YAML niet aan de OpenAPI specificatie. Voeg andere bewerkingen en antwoorddetails toe en controleer het volledige document daarna met een OpenAPI validator.
Verwante tools
De YAML naar JSON omzetter zet ondersteunde YAML invoer om naar JSON. SQL naar TypeScript leidt typedeclaraties af uit SQL structuren. De generator voor nagebootste API gegevens maakt rijen op basis van een JSON voorbeeldobject. Deze tool leidt een responseschema af uit JSON voorbeelden.