Validatore OpenAPI JSON

Errori JSON comuni che fanno fallire il controllo

Il JSON è più rigido dello YAML, quindi la maggior parte dei problemi in un file modificato a mano dipende dalla sintassi e non dal disegno dell’API. Le cause tipiche sono una virgola finale dopo l’ultima proprietà, apici singoli al posto di quelli doppi, un commento (il JSON non li ammette) o una graffa di chiusura mancante dopo un lungo oggetto paths. Un file danneggiato di solito termina con il messaggio “Impossibile leggere come JSON o YAML”, oppure con errori di campi mancanti perché non è stato letto nulla di utilizzabile.

Se vedi solo un errore di parsing, cerca per prima cosa l’errore di sintassi. I controlli strutturali vengono eseguiti quando il documento è letto come oggetto.

Un esempio pratico

Prendi questo piccolo documento:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

È leggibile, e il campo openapi e l’oggetto paths sono presenti. Il report mostrerebbe comunque:

Poiché c’è un errore, il documento non viene considerato valido. Aggiungi "version": "1.0.0" in info e rinomina la chiave in /orders. Una seconda esecuzione elimina entrambi i rilievi.

Cosa significa un esito positivo e cosa no

Un report pulito significa che la struttura portante è corretta. Non segue i collegamenti $ref, non controlla gli schema e non conferma che ogni operazione abbia delle risposte. Consideralo un controllo rapido prima di confermare il file, poi esegui un linter completo per le regole più approfondite.

Un flusso di lavoro pratico per le spec JSON

Conserva la spec nel controllo di versione e incollala qui prima di ogni commit che tocca paths. Poiché il controllo è rapido, funziona come verifica di sanità dopo aver unito modifiche di più persone, quando sono più probabili chiavi duplicate o una graffa fuori posto. Se il tuo JSON è generato da uno script di build, incolla l’output generato e non il template, così testi ciò che i lettori riceveranno davvero. Quando il report è pulito, condividi il file o passalo a un generatore di documentazione con più sicurezza che la struttura di primo livello sia solida.