Confronto fra documenti OpenAPI
OpenAPI Diff
Confronta due documenti OpenAPI e separa le modifiche che rompono la compatibilità da quelle che aggiungono soltanto.
Confronta due versioni di un documento OpenAPI e separa le modifiche in quelle che rompono la compatibilità e quelle additive. La regola che usa è scritta nella pagina: una modifica rompe la compatibilità se una richiesta che il vecchio documento accettava ora potrebbe essere rifiutata, oppure se una risposta che prometteva è una risposta che un client esistente non riesce più a gestire.
Documento precedente
Trascina qui la versione precedente
Letto solo in questa scheda.
Documento nuovo
Trascina qui la versione nuova
Letto solo in questa scheda.
Che rompono
8
Additive
7
Verdetto
Serve una versione maggiore
GET /pets
- rompeAdesso il parametro `in: query` `limit` è obbligatorio.
- aggiuntoÈ stato aggiunto un parametro `in: query` `sort` facoltativo.
- modificatoIl riepilogo o la descrizione è cambiato.
GET /pets · responses["200"].content["application/json"]
- rompe`[].id` ha cambiato tipo: da integer a string.
- rompeLa proprietà `[].name` adesso è facoltativa.
- rompe`[].status` ha guadagnato il valore di enum "pending".
- aggiuntoÈ stata aggiunta una proprietà facoltativa `[].owner`.
GET /pets/{petId} · responses["200"].content["application/json"]
- rompe`id` ha cambiato tipo: da integer a string.
- rompeLa proprietà `name` adesso è facoltativa.
- rompe`status` ha guadagnato il valore di enum "pending".
- aggiuntoÈ stata aggiunta una proprietà facoltativa `owner`.
GET /pets/{petId}
- rompeLa risposta `404` è sparita.
DELETE /pets/{petId}
- aggiuntoL’operazione è stata aggiunta.
components.schemas.Owner
- aggiuntoLo schema è stato aggiunto.
info.version
- modificato`1.0.0` → `2.0.0`
Che cosa conta come rottura
In una frase: una richiesta che il documento precedente accettava può ora essere rifiutata, oppure una risposta che prometteva è una che un client esistente non riesce più a gestire. Quindi: togliere un percorso, un’operazione, un codice di risposta, un tipo di media o una proprietà di risposta; aggiungere un parametro obbligatorio o una proprietà di richiesta obbligatoria; il passaggio da facoltativo a obbligatorio; un cambio di tipo; togliere un valore da un enum di richiesta; aggiungere un valore a un enum di risposta (lo switch del client non ha un case per quello); e una proprietà di risposta che passa da obbligatoria a facoltativa. Le direzioni opposte, e le modifiche a descrizioni, tag, operationId e marcature deprecated, sono compatibili.
- · Gli schemi vengono confrontati dopo aver seguito i
$refinterni al documento, quindi rinominare un componente non è una modifica. I parametri di percorso vengono abbinati per posizione e non per nome. - · L’interno di
oneOf·anyOf·notviene confrontato in blocco e segnalato come rottura se differisce — qui non ci si ragiona sopra. - · Un
$refche punta a un altro file non viene seguito. Unisci prima i file in uno solo.
Per controllare un solo documento, usa Verifica OpenAPI.
Come si usa
Mettere affiancati il documento vecchio e quello nuovo
JSON o YAML per entrambi. Vengono analizzati tutti e due in questa scheda, così una specifica non ancora pubblicata non esce dalla propria macchina.
Leggere il verdetto
Quante rompono la compatibilità, quante sono additive e che cosa significa per il numero di versione: un salto major, uno minor o niente del tutto perché il contratto non è cambiato.
Filtrare quelle che rompono la compatibilità e leggerle
Raggruppate per operazione, ciascuna con quello che è cambiato. La copia in Markdown ha la forma giusta per la descrizione di una pull request.
Domande frequenti
Perché aggiungere un valore a un enum di risposta rompe la compatibilità?
Perché un client esistente ha uno switch senza un caso per quel valore. Aggiungere a un enum di *richiesta* è sicuro: il server accetta più di prima; aggiungere a un enum di risposta manda ai client qualcosa di cui non era mai stato detto loro nulla. È la direzione a decidere.
Ho rinominato un componente e non segnala nessuna modifica.
Esatto. Gli schemi vengono confrontati dopo aver seguito i `$ref`, quindi un componente rinominato con la stessa forma è lo stesso contratto. I nomi dentro `components` sono interni; i client vedono la forma risolta.
Una proprietà obbligatoria di una risposta che diventa facoltativa rompe davvero la compatibilità?
Sì, dal lato del client. Gli era stato promesso che il campo ci sarebbe sempre stato e il suo codice lo legge senza condizioni; renderlo facoltativo vuol dire che ora il server può ometterlo. Obbligatorio e facoltativo si scambiano di verso fra richiesta e risposta, ed è la parte che ci si ricorda al contrario.
Come tratta `oneOf` e `anyOf`?
Vengono confrontati per intero e segnalati come rottura della compatibilità se differiscono in qualunque punto. Stabilire se un’unione sia un sovrainsieme di un’altra è una procedura di decisione che qui di proposito non si tenta; un falso «rompe la compatibilità» che si può scartare è meglio di un falso «sicuro» che non si può scartare.
Può ricevere da
Confronto fra due JSON
JSON Diff
Confronta due documenti JSON per struttura, ignorando l’ordine delle chiavi e riportando i percorsi aggiunti, tolti e cambiati.
Controllo di qualità di un OpenAPI
OpenAPI Linter
Controlla in un documento OpenAPI le risposte mancanti, gli schemi inutilizzati, i riferimenti che non puntano a niente e gli altri difetti che rompono i generatori di codice.
Verifica di intervalli semver
Semver Range Tester
Controlla quali versioni soddisfano un intervallo, confronta due versioni e ordina un elenco secondo la precedenza.
Formattatore e validatore JSON
JSON Formatter & Validator
Formatta, minifica e valida il JSON, indicando riga e colonna esatte di un errore di sintassi.
Dopo
Questi accettano ciò che produce questo strumento, così il risultato può passare direttamente.
Confronto fra due JSON
JSON Diff
Confronta due documenti JSON per struttura, ignorando l’ordine delle chiavi e riportando i percorsi aggiunti, tolti e cambiati.
Validatore di JSON Schema
JSON Schema Validator
Valida un documento rispetto a un JSON Schema e riporta ogni errore con il percorso dell’istanza.
Controllo di qualità di un OpenAPI
OpenAPI Linter
Controlla in un documento OpenAPI le risposte mancanti, gli schemi inutilizzati, i riferimenti che non puntano a niente e gli altri difetti che rompono i generatori di codice.
Verifica di intervalli semver
Semver Range Tester
Controlla quali versioni soddisfano un intervallo, confronta due versioni e ordina un elenco secondo la precedenza.
Conversione JSON ⇄ CSV
JSON ⇄ CSV
Appiattisce il JSON annidato in colonne o ricostruisce gli oggetti da una tabella, con i nomi di colonna a percorso puntato.
Formattatore e validatore JSON
JSON Formatter & Validator
Formatta, minifica e valida il JSON, indicando riga e colonna esatte di un errore di sintassi.