Questo visualizzatore e validatore OpenAPI legge un documento OpenAPI 3.0, 3.1 o Swagger 2.0 in YAML o JSON e lo mostra come documentazione API consultabile: ogni endpoint raggruppato per tag, con parametri, request body, risposte e schemi, più un comando cURL pronto da eseguire. Incolla la specifica o apri il file; non viene caricato nulla, quindi le API interne e non ancora pubblicate restano private.
Il validatore esegue 23 controlli strutturali tratti dalle specifiche, ciascuno elencato nella pagina: info e paths presenti, risposte con descrizione e codici di stato validi, ogni {parameter} di un path dichiarato come parametro di path obbligatorio, operationId univoci, $ref che si risolvono e requisiti di sicurezza che indicano uno scheme definito. Sono gli errori che mandano in crisi i generatori di codice e gli strumenti di documentazione. Non è una validazione completa rispetto al JSON Schema ufficiale della specifica, quindi una specifica che passa qui può avere ancora, per esempio, una parola chiave di schema scritta male. I $ref esterni ad altri file vengono elencati ma non scaricati.
Come si usa
- Incolla il tuo openapi.yaml, openapi.json o swagger.json, oppure apri il file. Per iniziare viene caricata un'API di esempio.
- Leggi la riga di stato e l'elenco Validazione. Ogni problema indica la regola e dove si trova (ad esempio paths./pets/{id}.get).
- Consulta la documentazione: le operazioni sono raggruppate per tag; fai clic su una per vederne parametri, request body, risposte e schemi.
- Filtra per path, summary o operationId per trovare un endpoint in una specifica grande.
- Copia l'esempio cURL di un'operazione e sostituisci il segnaposto <TOKEN> o <API_KEY> con le tue credenziali.
Domande frequenti
Come si visualizza un file Swagger o OpenAPI?
Incolla lo YAML o il JSON nella casella o apri il file. Il visualizzatore rileva la versione (swagger: "2.0" o openapi: 3.0.x / 3.1.x), elenca gli endpoint raggruppati per tag e ti permette di espanderli uno per uno per vederne parametri, request body, risposte e schemi risolti. Una volta caricata la pagina, funziona anche offline.
Cosa controlla il validatore OpenAPI?
Regole strutturali della specifica: un campo di versione supportato; info con title e version; path che iniziano con /; operazioni con responses non vuote, con descrizioni e codici di stato validi; parametri dei template di path dichiarati e obbligatori; parametri con name, un in valido e uno schema; nessun parametro od operationId duplicato; request body con content; $ref che si risolvono; requisiti di sicurezza che indicano scheme definiti. L'elenco completo è nella pagina sotto "Cosa viene controllato". Non valida ogni parola chiave degli schemi rispetto al JSON Schema ufficiale.
Perché un parametro di path non dichiarato è un errore?
La specifica richiede che ogni {name} in un template di path abbia un parametro corrispondente con in: path e required: true, a livello di path o di operazione. Alcuni validatori che controllano il documento solo rispetto al JSON Schema accettano un parametro mancante, ma poi i generatori di codice producono una funzione senza il relativo argomento e gli strumenti di documentazione mostrano un endpoint che non si può chiamare correttamente.
Legge OpenAPI 3.1 e Swagger 2.0?
Sì. I parametri body e formData di Swagger 2.0 vengono mostrati come request body, con produces e consumes come media type, così tutte e tre le versioni si leggono allo stesso modo. Le differenze di OpenAPI 3.1 sono rispettate: paths è facoltativo quando sono presenti components o webhooks, responses è facoltativo (qui un avviso) e type: [string, "null"] viene mostrato come nullable.
Carica i file $ref esterni?
No. Un $ref a un altro file o URL (per esempio ./schemas/user.yaml) viene elencato come avviso e mostrato come non risolto, perché la pagina non può leggere file che non hai aperto e non scarica URL di propria iniziativa. Unisci prima una specifica multi-file in un unico documento, per esempio con redocly bundle o swagger-cli bundle.
La mia specifica API viene caricata?
No. Parsing, validazione e rendering avvengono nel browser. La specifica non viene mai inviata da nessuna parte.
OpenAPI 3.x e Swagger 2.0: cosa è cambiato
• Campo di versione: swagger: "2.0" è diventato openapi: 3.0.x, poi 3.1.x.
• Server: la 2.0 ha host, basePath e schemes; la 3.x ha un elenco servers con variabili.
• Request body: la 2.0 usa un parametro con in: body (o formData); la 3.x ha requestBody con content per media type.
• Parti riutilizzabili: nella 2.0 definitions, parameters e responses al livello principale; la 3.x le mette sotto components, insieme a securitySchemes, requestBodies ed examples.
• La 3.1 allinea gli schemi a JSON Schema 2020-12: type può essere un elenco (["string", "null"] invece di nullable: true), examples è un array e vengono aggiunti i webhooks.
Gli errori che più spesso mandano in crisi gli strumenti API
• Parametri di path non dichiarati, o dichiarati senza required: true.
• Un $ref con un refuso (#/components/schema/User invece di schemas), che lascia vuota una parte della documentazione.
• operationId duplicati, che fanno fallire i generatori di codice o sovrascrivono metodi.
• Risposte senza description (è obbligatoria, anche se è solo "OK").
• Un requisito di sicurezza che indica uno scheme non definito, per cui il client generato non ha modo di autenticarsi.
