Softonic

Validatore OpenAPI

Passaggio 1 / 2
Avanti

Incolla un documento OpenAPI o Swagger, in JSON o YAML, e questo validatore ne controlla la struttura di base. Conferma che il documento venga analizzato, che abbia un campo della versione openapi o swagger, un oggetto info con titolo e versione e un oggetto paths, poi segnala i percorsi che non iniziano con una barra e i metodi HTTP sconosciuti. È un controllo di struttura rapido, non un validatore JSON Schema completo.

Come si svolge la convalida

  1. 1

    Incolla il documento

    JSON o YAML, per OpenAPI 2 (Swagger) o OpenAPI 3.

  2. 2

    Analizzalo

    Il validatore analizza il documento come JSON e ripiega sull'analisi YAML se questa fallisce.

  3. 3

    Controlla i campi obbligatori

    Conferma un campo della versione `openapi` o `swagger`, un oggetto `info` con `title` e `version` e un oggetto `paths`.

  4. 4

    Scansiona i percorsi

    Ogni percorso viene controllato per la barra iniziale, e ogni chiave di operazione viene confrontata con i metodi HTTP noti.

  5. 5

    Leggi il rapporto

    Gli errori bloccano la validità; gli avvisi segnalano i percorsi senza barra iniziale e i metodi sconosciuti.

Cosa controlla questo validatore

Controllo Esito in caso di fallimento
Il documento si analizza come JSON o YAML Errore
Campo openapi o swagger presente Errore
Oggetto info presente Errore
info.title presente Errore
info.version presente Errore
Oggetto paths presente Errore
Ogni percorso inizia con / Avviso
Le chiavi di operazione sono metodi HTTP noti Avviso

Un documento che supera tutti gli errori viene segnalato come strutturalmente valido. Gli avvisi non bloccano la validità; evidenziano ciò che vale la pena correggere.

Cosa non controlla

Questo è un controllo di struttura, non un validatore di specifica completo. Non:

  • convalida ogni nodo rispetto al JSON Schema ufficiale della tua versione;
  • risolve i riferimenti $ref né conferma che esistano i componenti a cui puntano;
  • controlla che i parametri di percorso siano dichiarati e usati in modo coerente;
  • verifica che i valori di operationId esistano o siano univoci;
  • segnala i numeri di riga degli errori.

Per quella profondità, esegui un validatore CLI dedicato come redocly lint, swagger-cli validate o spectral lint. Usa questo strumento per un rapido controllo prima di eseguire il commit o condividere una specifica.

Le versioni di OpenAPI nella pratica

Versione Note
Swagger 2.0 Ancora ampiamente distribuita; usa swagger: "2.0"
OpenAPI 3.0.x La linea 3.x più comune
OpenAPI 3.1.0 Allineata a JSON Schema 2020-12

Questo validatore accetta il campo openapi (3.x) o il campo swagger (2.0), quindi tutte superano il controllo della versione.

Un documento minimo che passa

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Ogni campo obbligatorio è presente, l’unico percorso inizia con una barra, e get è un metodo noto, quindi viene segnalato come strutturalmente valido.

Domande frequenti

Swagger era il nome originale della specifica, donata alla Linux Foundation nel 2015 e rinominata “OpenAPI” a partire dalla versione 3.0. “Swagger” ora si riferisce agli strumenti (Swagger UI, Swagger Editor). La specifica stessa è OpenAPI. Questo validatore accetta sia il campo della versione swagger (2.0) sia openapi (3.x).

No. Controlla la struttura di base: che il documento si analizzi, che abbia un campo della versione, un oggetto info con titolo e versione e un oggetto paths, e avvisa sui percorsi senza barra iniziale e sui metodi sconosciuti. Non convalida ogni nodo rispetto al JSON Schema ufficiale. Per questo usa redocly lint o spectral lint.

No. Non segue i riferimenti $ref né verifica che esistano i componenti a cui puntano. Per i riferimenti tra file, raggruppa prima il documento con uno strumento come redocly bundle o swagger-cli bundle, poi esegui un validatore completo.

No. Esamina solo il documento che incolli, non il codice in esecuzione. Non può sapere se la tua API restituisce davvero ciò che la specifica descrive. Lo fanno gli strumenti di contract testing come Dredd o Schemathesis.

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.

Riferimento ai caratteri HTML

Elenco ricercabile delle entità HTML, dei loro codici nominati e numerici, e copia con un clic per caratteri e simboli speciali.

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.

Riferimento scorciatoie da tastiera

Cerca le scorciatoie predefinite documentate di VS Code, Chrome e Bash con GNU Readline su macOS, Windows e Linux.

Creatore di diagrammi di flusso

Crea nel browser diagrammi di flusso visivi con cinque tipi di nodo, connessioni dirette e download SVG o PNG.

Promemoria Markdown

Riferimento pratico Markdown con anteprime reali ed esempi pronti da copiare per titoli, elenchi, tabelle, codice, link, immagini e sintassi GFM.

Strumento disponibile in altre lingue