Validatore Swagger 2.0

Cosa conta come esito positivo per uno Swagger 2.0

Per un file 2.0, il controllo della versione è soddisfatto da una chiave swagger di primo livello. Lo strumento non verifica che il valore sia "2.0", quindi non individua un numero sbagliato. Oltre alla versione, richiede info.title, info.version e un oggetto paths.

I campi specifici di Swagger 2.0, come host, basePath, schemes, definitions e securityDefinitions, non vengono esaminati. Un host mancante o un blocco definitions danneggiato non verranno segnalati.

Un esempio pratico

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

Il campo di versione, info e paths ci sono tutti, quindi non ci sono errori. Il report mostra un avviso:

Il documento risulta comunque valido, perché gli avvisi non ne bloccano la validità. Le chiavi di estensione del fornitore, come x-internal, sono legali in Swagger 2.0, quindi puoi lasciarle dove sono.

Migrare dalla 2.0

Se prevedi di passare a OpenAPI 3.x, puoi incollare il file convertito nella stessa casella e confrontare i risultati. Il controllo è lo stesso, con il campo openapi al posto di swagger. Per la migrazione vera e propria usa un convertitore e un linter completi, perché questo strumento non traduce le impostazioni di definitions né di host.

Quando basta un controllo rapido

Le definizioni Swagger 2.0 restano spesso per anni nei repository e vengono modificate a mano. Un controllo strutturale rapido è utile quando ne erediti una, quando uno strumento si rifiuta di caricarla e sospetti un campo mancante, o quando unisci due file e vuoi essere sicuro che il risultato conservi le sezioni info e paths. Per le regole complete della 2.0, incluse definitions e le impostazioni di sicurezza, prosegui con un linter dedicato.

Ricorda che un report pulito è un’affermazione sulla sola struttura. Operazioni senza risposte, tipi di parametro errati e riferimenti non risolti sono fuori da questo controllo, quindi testa il file anche nel tuo strumento di documentazione o di generazione del codice.