Compare specs
Une page dédiée (accessible depuis la sidebar sous « Compare specs ») qui récupère deux documents OpenAPI par URL et rapporte ce qui a changé entre eux : endpoints ajoutés, supprimés et modifiés, chacun marqué breaking ou informationnel.
Usage
Clique sur Compare specs dans la sidebar, colle une URL pour la spec de base (ancienne) et une pour la nouvelle spec (le champ nouveau est pré-rempli avec la spec actuellement chargée), puis clique sur Compare. Les deux documents passent par exactement le même pipeline normalizeDocument() que la visionneuse principale utilise, donc il n'y a pas de parseur séparé auquel faire confiance.
Ce qui compte comme breaking
| Change | Severity |
|---|---|
| Endpoint supprimé | Breaking |
| Nouveau paramètre requis | Breaking |
| Paramètre optionnel devenu requis | Breaking |
| Corps de requête devenu requis | Breaking |
| Une réponse 2xx a été supprimée | Breaking |
| Endpoint ajouté | Informationnel |
| Paramètre supprimé | Informationnel |
| Une réponse non-2xx a été supprimée | Informationnel |
| Nouveau statut de réponse documenté | Informationnel |
Périmètre
C'est volontairement superficiel : ça compare la présence des endpoints, la présence/le caractère requis des paramètres, le caractère requis du corps de requête, et les codes de statut des réponses. Ça ne fait pas de diff champ par champ des formes de schéma (par ex. une propriété qui passe discrètement de string à number n'est pas encore détectée).