API Contract Checker

Incolli (o carichi) una spec OpenAPI 3.x base (vecchia) e una di revisione (nuova), e lo strumento analizza ogni path, parametro, corpo della richiesta, risposta, requisito di sicurezza e schema in entrambe, poi riporta cosa è cambiato: endpoint aggiunti o rimossi, modifiche ai requisiti di parametri e campi della richiesta, tipi o enum ristretti, campi di risposta o codici di stato scomparsi, modifiche ai requisiti di sicurezza e modifiche alla composizione allOf/oneOf/anyOf.

Qualsiasi cosa che potrebbe far smettere di funzionare un client esistente: un endpoint rimosso, un parametro o campo della richiesta diventato obbligatorio, un campo di risposta o codice di stato rimosso, un campo non più garantito in una risposta, oppure un tipo/enum diventato più ristretto (inclusi gli array di tipi nullable di OpenAPI 3.1, ad esempio rimuovendo "null" da `["string", "null"]`). Nuovi endpoint, nuovi campi opzionali e nuovi campi di risposta sono additivi e vengono mostrati separatamente come sicuri.

Sì. Requisiti di sicurezza aggiunti/rimossi (globali e per singola operazione), modifiche alla definizione degli schemi di sicurezza (ad esempio una API key che passa da header a parametro di query), operazioni appena deprecate e modifiche agli URL del server vengono tutti riportati - come rilievi informativi anziché critici o sicuri, poiché (in linea con la gravità predefinita assegnata da oasdiff a questi controlli) nessuna delle due direzioni è universalmente giusta o sbagliata; decidi tu se è rilevante per la tua API.

Sì. I membri di `allOf` vengono risolti e uniti prima del confronto, quindi un campo obbligatorio aggiunto in profondità in uno schema composto viene comunque rilevato. Gli insiemi di varianti `oneOf`/`anyOf` vengono confrontati e segnalati come informativi quando una variante viene aggiunta o rimossa, poiché se quella specifica modifica sia critica dipende da come i tuoi client distinguono tra le varianti.

No - questo strumento confronta solo spec OpenAPI 3.x. Swagger 2.0 (il formato più vecchio) struttura parametri e corpi in modo diverso, quindi applicare le stesse regole darebbe risultati errati. Incollare un documento Swagger 2.0 produce un errore chiaro invece di un diff silenziosamente sbagliato.

No. Sia l'analisi che il confronto vengono eseguiti nel tuo browser - la tua spec non lascia mai il tuo dispositivo, a differenza della maggior parte degli altri strumenti di diff OpenAPI, che elaborano il caricamento sul proprio server anche quando dichiarano di non conservarlo. Questo vale anche quando usi l'opzione di caricamento/trascinamento file: il file viene letto localmente, mai trasmesso.

Confronta i corpi di richiesta e risposta `application/json`, che coprono la grande maggioranza delle API REST, ma non valuta altri content type, header di risposta, descrizioni o esempi. Un `$ref` che punta fuori dal documento (un file separato o un URL) viene segnalato come non risolvibile anziché ignorato silenziosamente.

Sì a entrambe le cose. Ogni riquadro accetta JSON o YAML indipendentemente e rileva quale hai usato, quindi puoi confrontare una spec base JSON con una revisione YAML o viceversa. Puoi anche trascinare un file .json/.yaml/.yml su uno dei riquadri, o usare il pulsante Upload file - il file viene letto nel tuo browser e non viene mai caricato altrove.

Funziona con qualsiasi documento che abbia un campo "openapi": "3.x" e un oggetto "paths", il che copre sia 3.0 che 3.1 - incluso il `type` in forma array di 3.1 (ad esempio `["string", "null"]`) - e rifiuta solo i documenti che sembrano Swagger 2.0.

Text (.txt), Markdown (.md) e JSON (.json) sono tutti supportati - scegline uno dal menu a tendina dei formati accanto a Download report prima di scaricare. L'esportazione JSON include l'elenco completo dei rilievi oltre ai conteggi per gravità, quindi può essere inviata a un altro script (ad esempio un controllo CI) se ti serve.

Funzionano entrambi: premi Confronta per una riesecuzione immediata, oppure continua semplicemente a digitare - dopo una breve pausa si confronta automaticamente. Puoi anche premere Ctrl+Enter (Cmd+Enter su Mac) da uno dei due riquadri per confrontare subito senza attendere.