Rivedere un contratto API
Controlla un file prima del commit o della consegna a un altro sviluppatore.
Validatore OpenAPI e Swagger
Controlla una descrizione API in JSON o YAML senza caricarla su un server.
Incolla o importa un documento JSON/YAML autonomo e avvia la validazione. Il rapporto elenca gli errori e spiega l’ambito dei controlli.
Dati non inviati
Rapporto di validazione
Controlli parziali: struttura, riferimenti JSON Pointer, parole chiave degli schemi 3.1, identificatori di percorsi e webhook e parametri di percorso. Formati ed esempi non vengono validati; i vincoli semantici dei callback non vengono controllati. Dialetti personalizzati, $id, ancore e riferimenti dinamici non sono supportati.
Questo strumento ti è stato utile?
Come funziona questo strumento?
Una descrizione OpenAPI funge da contratto tra chi sviluppa, documenta e utilizza un’API. Un rientro YAML errato, un campo obbligatorio mancante o un riferimento non risolvibile possono impedirne l’uso. Questo validatore aiuta a individuare tali errori in JSON o YAML direttamente nel browser. Supporta Swagger 2.0, OpenAPI 3.0.0–3.0.4 e OpenAPI 3.1.0–3.1.2, entro l’ambito indicato nel rapporto.
Il controllo parte dalla sintassi: il testo deve essere interpretabile come un unico documento JSON o YAML senza chiavi duplicate. Si verificano poi la versione e la struttura prevista, comprese le informazioni dell’API e le operazioni descritte. Un file sintatticamente corretto può quindi non rispettare lo schema OpenAPI della sua versione.
I riferimenti interni usano JSON Pointer, per esempio #/components/responses/Ok, per indicare posizioni nello stesso documento. Il validatore ne verifica la risoluzione e distingue i riferimenti effettivi dalle chiavi $ref nei dati di un esempio. I rimandi ad altri file o schemi remoti vengono rifiutati: nessun risolutore li scarica.
Ulteriori controlli riguardano gli operationId di percorsi e webhook, i parametri di percorso e i tipi delle parole chiave degli schemi 3.1. Un esito positivo resta parziale: non verifica tutti i vincoli semantici, i formati o la validità degli esempi. Dialetti personalizzati, $id, ancore e riferimenti dinamici sono segnalati come non supportati.
Un percorso diagnostico come /paths/~1health/get/responses indica il campo responses di GET /health: in JSON Pointer, ~1 rappresenta una barra obliqua. Quando è possibile individuare la posizione nel testo sorgente, viene mostrata la riga. Correggi prima la prima causa chiara, poi affronta i messaggi secondari dello stesso oggetto incompleto.
Come usare questo strumento
Fornire il documento
Incolla la descrizione o importa un file JSON, YAML o YML. Riunisci prima i riferimenti distribuiti tra più file.
Avviare i controlli
Premi Valida. L’elaborazione resta nel browser e si interrompe dopo un massimo di dieci secondi.
Correggere i percorsi indicati
Parti dagli errori di sintassi, correggi i campi segnalati e ripeti la validazione.
Casi d’uso
Diagnosticare un’esportazione
Individua errori di struttura in descrizioni prodotte da framework o generatori.
Esaminare un’API privata
Analizza una descrizione interna senza caricarne il contenuto né chiamare gli endpoint.
Esempi
Un documento autonomo con un riferimento interno
Incolla questo documento completo per descrivere GET /health. La risposta 200 riutilizza il componente Ok dello stesso file. Si verifica un contratto documentale; non viene inviata alcuna richiesta GET a un server.
Input
openapi: 3.1.0
info:
title: Health API
version: 1.0.0
paths:
/health:
get:
responses:
"200":
$ref: "#/components/responses/Ok"
components:
responses:
Ok:
description: OKRisultato
Valida nell’ambito verificato
Operazioni HTTP dichiarate: 1Un campo obbligatorio mancante
Questo YAML è interpretabile, ma manca info.version. Aggiungi, per esempio, version: 1.0.0 all’interno di info. Un oggetto paths vuoto non è, da solo, la causa dell’errore. La riga indicata dipende dalla posizione del campo nel tuo file.
Input
openapi: 3.1.0
info:
title: Health API
paths: {}Risultato
Descrizione da correggere
Percorso: /info
Struttura non conforme alla specifica.
Dettaglio: required: versionUn riferimento interno non risolvibile
Il documento contiene ancora il componente Ok, ma la risposta richiede Absent. Correggi il nome nel riferimento. Se lo sostituisci con un URL esterno, il messaggio diventa un riferimento esterno rifiutato e il file remoto non viene caricato.
Input
openapi: 3.1.0
info:
title: Health API
version: 1.0.0
paths:
/health:
get:
responses:
"200":
$ref: "#/components/responses/Absent"
components:
responses:
Ok:
description: OKRisultato
Descrizione da correggere
Percorso: /paths/~1health/get/responses/200/$ref
Riferimento interno non trovato.Consigli e buone pratiche
- info.version è la versione della tua API; openapi indica la versione del formato di descrizione. Non sono intercambiabili.
- Un percorso /users/{id} deve dichiarare il parametro id nel percorso o nell’operazione. Un parametro di query chiamato id non sostituisce un parametro di percorso.
- Per più file, genera prima un documento autonomo con il tuo consueto strumento di raggruppamento. Il limite è un milione di caratteri; anche alias YAML e complessità sono limitati, con un tempo massimo di dieci secondi.
Fonti e riferimenti
- OpenAPI Specification v2.0 (si apre in una nuova scheda), OpenAPI InitiativePagina in inglese
- OpenAPI Specification v3.0.4 (si apre in una nuova scheda), OpenAPI InitiativePagina in inglese
- OpenAPI Specification (si apre in una nuova scheda), OpenAPI InitiativePagina in inglese
Domande frequenti
Una validazione riuscita garantisce che l’API funzioni?
No. Il validatore controlla parte della descrizione, non le risposte del server, i diritti di accesso o le regole di business. Nessun endpoint viene chiamato. Il rapporto spiega i limiti dei controlli.
Come controllo una descrizione su più file?
Riuniscila localmente in un documento autonomo con i tuoi strumenti. Nessun file collegato viene scaricato.
OpenAPI 3.2 è supportato?
Non ancora in questa versione. Una versione non supportata viene segnalata senza confonderla con un errore di sintassi.
Quali controlli vengono eseguiti?
Il documento viene verificato rispetto allo schema strutturale della sua versione. Si controllano anche i riferimenti JSON Pointer interni, i tipi delle parole chiave degli schemi 3.1, gli operationId di percorsi e webhook e i parametri di percorso. Non vengono verificati tutti i formati, gli esempi, i dati reali e gli altri vincoli semantici.
Strumenti correlati
Continua con questi strumenti
Strumenti simili o complementari a questo.
Strumenti simili
Valida un documento JSON con uno schema e individua con precisione ogni errore.
SviluppoIn evidenzaUsa questo strumento
Converti dati JSON in YAML o YAML in JSON direttamente nel browser.
SviluppoUsa questo strumento
Crea una richiesta API HTTP completa con metodo, URL, parametri, intestazioni e corpo.
SviluppoUsa questo strumento