Validatore OpenAPI 3.1
Incolla un documento OpenAPI 3.1 in JSON o YAML per controllarne la struttura di primo livello. Lo strumento cerca il campo openapi, un oggetto info con title e version e un oggetto paths. È un controllo strutturale: non valida le parole chiave degli schema della 3.1, e alcuni schemi compatibili con la 3.1 producono un avviso o un errore che conviene conoscere.
Come controllare un documento 3.1
-
1
Incolla la spec 3.1
Incolla il documento con `openapi: 3.1.0` (o un altro valore 3.1.x) nel campo, in JSON o YAML.
-
2
Avvia il controllo
Passa al passaggio dei risultati per vedere errori e avvisi.
-
3
Leggi le note sulla 3.1
Verifica se un elemento segnalato è un vero errore o uno degli schemi della 3.1 descritti più sotto.
-
4
Completa con un linter completo
Quando la struttura è pulita, usa un validatore completo per le regole di JSON Schema 2020-12.
Cosa fa questo strumento con i file 3.1
La versione 3.1 allinea gli schema a JSON Schema 2020-12. Questo validatore non legge il contenuto degli schema. Ispeziona solo il primo livello e le voci dei percorsi, quindi le funzionalità degli schema della 3.1, come gli array di tipi o const, non superano né falliscono il controllo. Anche il valore della versione non viene verificato: qualsiasi campo openapi risulta presente.
Due schemi della 3.1 da tenere d’occhio
| Schema nel tuo file 3.1 | Cosa segnala lo strumento |
|---|---|
Oggetto webhooks e nessun oggetto paths |
Errore: oggetto ‘paths’ mancante. |
Operazione trace sotto un percorso |
Avviso: metodo sconosciuto ‘trace’ sul percorso |
$ref come chiave di un elemento di percorso |
Avviso: metodo sconosciuto ‘$ref’ sul percorso |
OpenAPI 3.1 consente di descrivere solo i webhook e di omettere paths. Questo strumento richiede paths, quindi un file del genere viene segnalato con un errore anche se la specifica lo permette. Aggiungere un oggetto vuoto paths: {} soddisfa il controllo.
L’elenco dei metodi usato qui comprende get, post, put, patch, delete, head, options, oltre a parameters, summary, description e servers. Il metodo trace esiste nella specifica ma non è in questo elenco, quindi genera un avviso che puoi ignorare se è intenzionale. Gli avvisi non rendono il documento non valido.
Un esempio pratico
openapi: 3.1.0
info:
title: Events API
version: 2.0.0
webhooks:
newEvent:
post:
summary: Event delivered
Risultato: un errore, “Oggetto ‘paths’ mancante.” Aggiungi paths: {} e la struttura viene superata.
Quando basta questo strumento e quando serve altro
Usa questa pagina per confermare che un file 3.1 abbia la forma corretta prima di aprire una pull request o di condividerlo con un partner. I controlli sono rapidi e i messaggi sono chiari. Una volta sistemata la struttura, le regole degli schema 3.1 richiedono comunque un linter completo, perché lì si nascondono la maggior parte degli errori reali: dichiarazioni di tipo non valide, riferimenti interrotti e definizioni di risposta mancanti. Considera i due passaggi complementari, non alternativi.
Se un avviso è intenzionale, come nel caso di trace, annotalo nella pull request perché i revisori non si chiedano il motivo. Gli avvisi non cambiano mai il risultato valido, quindi possono essere mantenuti senza problemi. Gli errori sono le voci da risolvere prima di condividere il file.
Domande frequenti
No. Non esamina il contenuto degli oggetti schema, quindi le parole chiave di JSON Schema 2020-12 non vengono controllate. Copre solo la struttura di primo livello e le voci dei percorsi.
Il controllo richiede un oggetto paths. Un file 3.1 con solo webhook non ne ha uno, quindi segnala un errore di paths mancante. Aggiungi un paths: {} vuoto per superarlo.
No. Verifica solo che esista un campo openapi o swagger, non quale sia il suo valore.
Non necessariamente. trace è un’operazione valida nella specifica. Lo strumento semplicemente non la include nel suo elenco di metodi noti.
Strumenti correlati
Riferimento Tabella ASCII
Tabella ASCII completa da 0 a 127 con decimale, esadecimale, ottale, binario e riferimento numerico HTML per ogni carattere, inclusi i codici di controllo come NUL, LF e DEL.
Generatore di lettere casuali
Genera lettere A-Z casuali. Scegli la quantità, usa maiuscole, minuscole o un mix, e applica il risultato a giochi, spunti o attività in classe.
Generatore di numeri telefonici fittizi
Genera fino a 50 numeri fittizi da intervalli ufficiali riservati in cinque paesi.
Convertitore da HTML a immagine
Trasforma HTML e CSS in un PNG o JPG di dimensioni fisse nel browser. Scegli area e scala, controlla l'anteprima e scarica in locale.
Validator XSD
Valida un documento XML rispetto a uno schema XSD e segnala le discrepanze tra elementi e tipi con numeri di riga esatti.
Convertitore RGB in HEX
Converti i valori rgb() nella forma esadecimale #rrggbb utilizzata in CSS e negli strumenti di design. Gestisce la forma abbreviata a 3 cifre e rgba con alpha.
Strumento disponibile in altre lingue
- ตัวตรวจสอบ OpenAPI 3.1 [TH]
- Walidator OpenAPI 3.1 [PL]
- Công cụ kiểm tra OpenAPI 3.1 [VI]
- Validator OpenAPI 3.1 [ID]
- مدقق OpenAPI 3.1 [AR]
- OpenAPI 3.1 Validator [DE]
- OpenAPI 3.1 バリデーター [JA]
- Validador OpenAPI 3.1 [PT]
- Validador de OpenAPI 3.1 [ES]
- OpenAPI 3.1 검증기 [KO]
- OpenAPI 3.1-validerare [SV]
- Validateur OpenAPI 3.1 [FR]
- OpenAPI 3.1 Validator [NL]
- OpenAPI 3.1 Validator [EN]
- Валидатор OpenAPI 3.1 [RU]
- OpenAPI 3.1 Doğrulayıcı [TR]
- OpenAPI 3.1 验证器 [ZH]