Validatore OpenAPI
Controlla un documento OpenAPI 3.0, 3.1 o 3.2 oppure Swagger 2.0 in YAML o JSON e ottieni un riepilogo dei suoi endpoint e schemi. Il validatore controlla i campi obbligatori, i modelli dei percorsi rispetto ai parametri di percorso, la posizione dei parametri, i codici di risposta, gli ID operazione duplicati e ogni $ref locale, e indica la posizione di ciascun problema.
Domande frequenti
Che cosa controlla il validatore?
Controlla la versione openapi o swagger, info.title e info.version, che i percorsi inizino con una barra, che ogni {parameter} in un percorso abbia un parametro di percorso obbligatorio corrispondente e viceversa, i nomi e le posizioni dei parametri, i codici di stato e le descrizioni delle risposte, i parametri duplicati, i valori operationId duplicati e che ogni $ref locale punti a qualcosa nel documento.
È una convalida completa della specifica secondo lo schema JSON?
No. Controlla le regole strutturali indicate sopra, che permettono di individuare la maggior parte degli errori nei documenti scritti a mano, ma non convalida ogni campo rispetto al metaschema ufficiale né controlla il contenuto degli schemi.
Che cosa mostra il riepilogo?
La versione della specifica e di API, il titolo, una tabella di tutti gli endpoint con metodo, percorso, operationId, riepilogo e codici di risposta, nonché i nomi degli schemi in components.schemas o, per Swagger 2.0, in definitions.
I riferimenti esterni vengono seguiti?
No. I riferimenti ad altri file o URL non vengono recuperati né segnalati. Vengono risolti nel documento incollato solo i riferimenti che iniziano con #.
Qual è la differenza tra errori e avvisi?
Gli errori indicano la violazione di una regola della specifica, per esempio una descrizione della risposta mancante o un parametro di percorso non dichiarato. Gli avvisi segnalano elementi consentiti ma di solito involontari, come un'operazione GET con un corpo della richiesta o un documento senza alcun operationId.
OpenAPI 3.1 modifica i requisiti?
Sì. In OpenAPI 3.1 e 3.2 un'operazione non richiede più un oggetto responses e un documento può contenere webhook o components invece di paths. Il validatore applica queste regole quando il campo openapi inizia con 3.1 o 3.2.