Vai al contenuto

Visualizzatore e validatore OpenAPI e Swagger — YAML o JSON

Incolla una specifica OpenAPI 3.x o Swagger 2.0 per consultarla come documentazione raggruppata per tag, verificarne gli errori strutturali e ottenere un esempio cURL per ogni endpoint.

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 operazioni · 1 errore, 0 avvisi

Validazione

  • Errore Il path usa {itemId} ma non è dichiarato alcun parametro in: path chiamato "itemId".
    in paths./orders/{orderId}/items/{itemId}.get
Cosa viene controllato

Il visualizzatore verifica queste regole strutturali delle specifiche OpenAPI 3.0 / 3.1 e Swagger 2.0. Non è una validazione JSON Schema completa del documento: le singole parole chiave degli schemi (minimum, pattern, format…) non vengono controllate.

  • Il documento è YAML o JSON valido.
  • Dichiara openapi: 3.0.x o 3.1.x, oppure swagger: "2.0".
  • info esiste con title e version (stringhe).
  • paths esiste (facoltativo nella 3.1 quando sono presenti components o webhooks).
  • Ogni path inizia con /.
  • I path item contengono solo metodi HTTP, parameters, $ref, summary, description, servers (o estensioni x-).
  • Ogni operazione ha responses (errore nella 2.0 e nella 3.0, avviso nella 3.1).
  • responses non è vuoto.
  • Le chiavi delle risposte sono codici di stato (200), default o (3.x) intervalli come 2XX.
  • Ogni risposta ha una description.
  • I valori di operationId sono univoci.
  • Ogni {name} in un path ha un parametro in: path corrispondente.
  • Ogni parametro in: path compare nel path.
  • I parametri di path hanno required: true.
  • Ogni parametro ha name e in.
  • in è query, header, path o cookie (2.0: query, header, path, formData o body).
  • Nessun parametro compare due volte con lo stesso name e in.
  • I parametri hanno uno schema o un content (2.0: i parametri body hanno uno schema, gli altri un type).
  • 2.0: al massimo un parametro body, e non insieme a formData.
  • 3.x: requestBody ha content.
  • Ogni $ref locale (#/…) punta a qualcosa che esiste.
  • I riferimenti ad altri file o URL vengono segnalati (non vengono scaricati).
  • I requisiti di sicurezza indicano un security scheme definito.

Documentazione: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

URL di base: https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

Schemi

NewBook
Book
Author
OrderItem

Funziona interamente nel browser. La tua specifica API non viene mai caricata e i $ref esterni non vengono scaricati. Sfoglia tutti gli strumenti gratuiti.

Hai trovato un problema o qualcosa che potrebbe andare meglio? Leggiamo ogni messaggio e sistemiamo le cose in fretta.

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

  1. Incolla il tuo openapi.yaml, openapi.json o swagger.json, oppure apri il file. Per iniziare viene caricata un'API di esempio.
  2. Leggi la riga di stato e l'elenco Validazione. Ogni problema indica la regola e dove si trova (ad esempio paths./pets/{id}.get).
  3. Consulta la documentazione: le operazioni sono raggruppate per tag; fai clic su una per vederne parametri, request body, risposte e schemi.
  4. Filtra per path, summary o operationId per trovare un endpoint in una specifica grande.
  5. 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.