Generatore di schemi di risposta da JSON a OpenAPI
Deduce uno schema di risposta da esempi JSON e genera un percorso YAML OpenAPI 3.0.3.
Come funziona
Incolla un esempio JSON di risposta, inserisci un percorso letterale e scegli GET, POST, PUT o DELETE. Il generatore deduce uno schema del corpo della risposta e lo inserisce in un documento YAML OpenAPI 3.0.3.
Usa esempi rappresentativi per mostrare le variazioni possibili della risposta. Quando più oggetti si trovano nella stessa posizione di un array, il generatore combina le proprietà e ne segna una come obbligatoria solo se è presente in ogni oggetto osservato.
Controlla i tipi dedotti e i campi obbligatori prima di usare lo YAML. Aggiungi i corpi delle richieste, i parametri, l’autenticazione, le risposte di errore e le dichiarazioni dei parametri di percorso. Poi verifica il documento completo con un validatore OpenAPI.
Usa questo strumento quando hai esempi JSON ma non uno schema di risposta. Documenta solo il percorso e il metodo selezionati a partire dall’esempio fornito.
Passo dopo passo
- Incolla un esempio JSON di risposta
- Imposta un percorso letterale e scegli il metodo
- Controlla e copia lo schema di risposta
Esempio svolto
Per GET /api/users, incolla {"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}. L’esempio contiene oggetti annidati, valori misti in un array e due oggetti di metriche.
L’output indica come obbligatori user, tags e metrics. Entrambi gli oggetti di metriche contengono count, quindi è obbligatorio anche lì. score e active compaiono ciascuno in un solo oggetto, perciò sono facoltativi. tags accetta una stringa o un intero; entrambi i tipi osservati sono nullable perché l’esempio contiene anche null.
Quando usare questo strumento
Usa il generatore per convertire corpi JSON di risposta di esempio in uno schema OpenAPI iniziale mentre documenti un percorso.
Aiuta a organizzare le forme di risposta osservate. Il documento generato richiede ancora i dettagli di richiesta, sicurezza, errori e parametri previsti dall’API.
Errori comuni
Un solo oggetto fa apparire obbligatorie tutte le proprietà incluse. Per identificare le proprietà che variano tra le risposte, fornisci più oggetti rappresentativi nella stessa posizione di un array.
Non considerare l’output dedotto una definizione API completa. Controlla la gestione di null, i campi facoltativi, le varianti degli array e i percorsi letterali. Aggiungi i dettagli di richiesta ed errore che non rientrano nello scopo dello strumento.
Regole di deduzione
Per ogni posizione di un oggetto, chiavi obbligatorie = chiavi presenti in ogni oggetto osservato.
Per ogni valore, schema dedotto = unione dei tipi non null osservati.
Quando null è osservato insieme a un tipo noto, lo schema tipizzato viene marcato nullable.
La deduzione usa esempi e non verifica un contratto durante l’esecuzione. Un solo esempio non mostra quali campi possono mancare nelle risposte di produzione.
Limiti e ipotesi
Il risultato descrive i valori osservati nell’esempio. Non identifica i campi assenti da tutti gli esempi, non dimostra che un campo sia facoltativo in produzione e non deduce il tipo degli elementi di un array vuoto. Un valore presente solo come null non ha un tipo deducibile. I valori misti sono rappresentati come alternative da confrontare con il contratto API.
Termini chiave
- Documento OpenAPI
- Un documento OpenAPI descrive percorsi, operazioni, input, risposte e altri dettagli di un’API in un formato leggibile dalle macchine.
- Schema
- Uno schema descrive la struttura attesa e i tipi di valore dei dati, per esempio un oggetto con proprietà denominate.
- Proprietà obbligatoria
- In questo output, obbligatorio significa che la proprietà è comparsa in ogni oggetto osservato in quella posizione. Non dimostra il comportamento in produzione.
Confronta gli strumenti correlati
Usa il convertitore YAML a JSON per ottenere JSON da un input YAML supportato. Usa SQL a TypeScript per ricavare tipi TypeScript da una definizione di tabella. Questo strumento deduce uno schema di risposta da esempi JSON.
Il generatore di dati simulati per API crea righe da un oggetto JSON di esempio. Questo strumento deduce uno schema di risposta da un esempio JSON e non genera dati simulati.
FAQ
Come diventa l’esempio uno schema di risposta?
Il generatore esamina ogni valore dell’esempio JSON. Crea proprietà per gli oggetti, controlla tutti gli elementi degli array e combina i tipi osservati con anyOf quando serve. Per esempio, l’array tags dell’esempio contiene stringhe, null e un intero, quindi lo schema degli elementi ammette una stringa nullable o un intero nullable.
Come vengono rappresentati null e i tipi diversi?
Gli oggetti diventano schemi con proprietà. Una proprietà è obbligatoria quando è presente in tutti gli oggetti osservati in quella posizione. Valori con tipi osservati diversi usano anyOf. Se vengono osservati null e un altro tipo, lo schema tipizzato riceve nullable: true. Un valore presente solo come null non ha un tipo deducibile e il suo schema resta senza vincoli.
Che cosa include il documento generato?
Il documento contiene un percorso, il metodo scelto GET, POST, PUT o DELETE e una risposta JSON riuscita con stato 200. Lo schema è in components e viene richiamato dalla risposta. Il generatore non crea corpo della richiesta, parametri, regole di sicurezza, risposte di errore o intestazioni.
Posso inserire un parametro di percorso come un ID?
Il percorso deve essere letterale e iniziare con una barra, per esempio /api/users. I percorsi con parentesi graffe sono rifiutati perché un modello come /api/users/{id} richiede anche un parametro di percorso dichiarato, che questo generatore non aggiunge.
Genera o convalida un contratto API completo?
No. L’output descrive il corpo di una risposta di esempio. Non deduce schemi di richiesta e non convalida lo YAML generato rispetto alla specifica OpenAPI. Aggiungi le altre operazioni e i dettagli della risposta, poi controlla il documento completo con un validatore OpenAPI.
Strumenti correlati
Il convertitore YAML a JSON converte input YAML supportati in JSON. SQL a TypeScript ricava dichiarazioni di tipo da strutture SQL. Il generatore di dati simulati per API crea righe da un oggetto JSON di esempio. Questo strumento deduce uno schema di risposta da esempi JSON.