Validatore OpenAPI YAML

Perché l’indentazione conta per il risultato

In YAML l’annidamento delle chiavi stabilisce a quale oggetto appartiene ogni campo. Se version si trova allo stesso livello di info invece che un livello più in basso, il documento resta YAML leggibile, ma info.version manca e il controllo lo segnala. Lo stesso vale per paths: una chiave di percorso indentata per errore sotto info fa scomparire l’oggetto paths di primo livello.

Usa gli spazi, non le tabulazioni, e mantieni un passo costante, per esempio due spazi per livello.

Un esempio pratico

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

Il campo version, info.title e paths sono presenti, e /pets inizia con la barra con get come metodo noto. Manca una cosa: info.version. Il report elenca:

Aggiungi version: 1.0.0 sotto info, indentato di due spazi, e il documento risulta strutturalmente valido.

Mantieni i documenti semplici per una lettura affidabile

Il controllo legge al meglio le normali mappature YAML: righe chiave: valore semplici, annidate con un’indentazione coerente. Se un documento con funzionalità YAML avanzate, come ancore o blocchi su più righe, viene segnalato come illeggibile o mostra campi mancanti, prova una copia JSON della stessa spec per capire se il problema sta nel contenuto o nella sintassi YAML.

Un risultato pulito conferma solo lo scheletro. Non risolve i collegamenti $ref né controlla gli schema.

Un flusso di lavoro pratico per le spec YAML

Modifica a piccoli passi e ricontrolla spesso. Dopo aver aggiunto un percorso o spostato un blocco, incolla di nuovo il file, così un’indentazione sbagliata viene individuata mentre la modifica è ancora fresca. Quando dividi una spec grande in più file, incolla la versione unita, perché questo controllo legge solo il testo che gli fornisci e non carica gli altri file. Copia dall’editor e non da una pagina renderizzata, perché le pagine web possono sostituire spazi e virgolette con caratteri simili che cambiano la lettura dello YAML.

Infine, ricorda che il report elenca solo ciò che il controllo riesce a vedere. Un risultato pulito su un file YAML significa che lo scheletro di primo livello è corretto, non che ogni operazione, schema o riferimento al suo interno lo sia.