Indicateur susceptible de rompre les modifications apportées à OpenAPI avant la publication

Réponse directe

Diff Anything peut-il détecter les changements incompatibles OpenAPI ?

Diff Anything compare les schémas OpenAPI et JSON en tant que contrats analysés et étiquettes susceptibles de rompre les modifications avec des codes de règles heuristiques, telles qu’une opération supprimée ou une nouvelle entrée requise. Avec Pro sur Windows, le CLI et les manifestes par lots exécutent la même comparaison dans CI : les schémas identiques réussissent et --fail-on breaking fait échouer le travail uniquement en cas de rupture ou de modifications non classifiées, avec le code de règle de chaque résultat dans JUnit et SARIF. Les règles sont heuristiques, donc les résultats signalés et réussis nécessitent toujours une révision contractuelle.

Schémas pris en charge

Schéma OpenAPI, JSON, GraphQL et tables SQL.

Le mode Schéma API compare les documents de schéma OpenAPI et JSON écrits en JSON ou YAML. Les détecte automatiquement à partir des clés de niveau supérieur telles que openapi, swagger ou $schema. Le même mode lit également le type GraphQL, les définitions d’interface et d’entrée, ainsi que les instructions SQL CREATE TABLE.

Chaque modification est répertoriée avec son emplacement, par exemple $.paths["/users"].get.parameters[0]. Si les deux côtés sont écrits dans des langages de schéma différents, le résultat indique que la classification est uniquement structurelle.

Règles de rupture-changement

Les modifications incompatibles probables sont étiquetées avec un code de règle.

Chaque différence est vérifiée par rapport à un ensemble de règles de compatibilité. Une correspondance est étiquetée «  Modification de rupture API » avec son code de règle, et le filtre de rupture dans la liste des différences affiche uniquement ces éléments. Une note au-dessus du résultat donne le verdict, tel que « 2 changements API potentiellement cassants détectés par les règles heuristiques ». Les schémas identiques ou équivalents, y compris le même schéma écrit une fois dans JSON et une fois dans YAML, ne signalent aucune différence.

• API001 : une opération, un paramètre, une réponse ou un chemin a été supprimé
• API002 : un membre de champ, de colonne ou de type a été supprimé
• API003 : une valeur a été supprimée d’une énumération, oneOf ou anyOf
• API004 : une nouvelle entrée obligatoire a été ajoutée
• API005 : une valeur facultative ou nullable est devenue obligatoire
• API006 et API007 : une contrainte minimale ou maximale devenue plus stricte
• API008 : des exigences de sécurité ont été ajoutées ou modifiées
• API009 : le type, le format ou $ref d’un schéma a été modifié, ou une valeur dans ses propriétés a changé de type
• API010 : une signature de champ GraphQL ou une définition de colonne SQL modifiée

Comment le lire

Traitez le classement comme une aide à la révision.

Les règles déterminent où se situe une modification dans le document. Ils ne distinguent pas les schémas de requête des schémas de réponse, donc une nouvelle propriété de réponse obligatoire est marquée de la même manière qu’un nouveau champ de requête obligatoire. Les références ($ref) sont comparées telles qu’écrites et non résolues : une référence modifiée est signalée sous API009, mais le schéma vers lequel elle pointe n’est pas comparé. Les modifications apportées aux mots-clés tels que le modèle sont répertoriées sans code de règle. La suppression d’une entrée entière sous composants, le renommage ou le déplacement d’un paramètre, l’ajout de propriétés supplémentaires : false et la suppression des exigences de sécurité ne sont pas classés comme des ruptures.

Les tableaux tels que les paramètres sont comparés par position, donc l’insertion d’un paramètre peut également afficher les modifications aux positions ultérieures. Lisez chaque élément signalé avant de décider si les clients sont concernés. Le résultat est le même : lorsqu’aucune règle ne correspond, une révision manuelle du contrat est toujours requise.

Portail CI

Échec d’une tâche CI uniquement en cas de modifications incompatibles avec Pro.

Avec Pro sur Windows, --mode api exécute la comparaison à partir de la ligne de commande avec une sortie résumé, terminal ou JSON. Ajoutez --fail-on breaking et la commande renvoie 1 uniquement lorsqu’une modification est interrompue ou n’a pas pu être classée ; les schémas identiques et les modifications ininterrompues renvoient 0.

Dans un manifeste de lot, définissez failOn : Breaking sur un cas API. La sortie JUnit répertorie les modifications incompatibles avec leurs codes de règle, et SARIF rapporte chaque résultat comme son propre résultat, avec les modifications incompatibles sous leur code de règle comme erreurs. Les règles sont heuristiques, alors considérez la réussite du contrôle comme une première porte, et non comme une preuve que les clients ne sont pas affectés.

Idéal pour

Où s’inscrit ce flux de travail.

• Examen d’une modification de schéma OpenAPI ou JSON avant sa diffusion auprès des clients
• Obtenir une première liste des changements probables à vérifier manuellement
• Comparaison des définitions API qui doivent rester sur votre propre machine

Aucun compte, service de comparaison cloud, analyse ou télémétrie.

Capacités pertinentes

Ce que Diff Anything apporte au travail.

Flux de travail pratique

De la configuration à un résultat révisé.

1. Ouvrir les spécifications publiées et candidates

   Choisissez les deux fichiers de schéma OpenAPI ou JSON. Les ouvre automatiquement en mode schéma API.

2. Filtre à rupture

   Utilisez le filtre Breaking pour voir en premier les modifications qui correspondent à une règle de compatibilité.

3. Vérifiez chaque changement signalé

   Lisez le code et l’emplacement de la règle, puis décidez si cela affecte les demandes, les réponses ou ni l’un ni l’autre.

4. Vérifier les modifications restantes

   Revenez à Tous pour vérifier les modifications que les règles ne classent pas, telles que les modifications de modèle ou un paramètre renommé.

Utile en pratique

Réponses directes

Questions sur l’outil de comparaison OpenAPI.

Aller plus loin

Sous Windows, lancer des comparaisons reproductibles, comprendre les codes de sortie, intégrer Git et produire des résultats lisibles par une machine pour la CI.

Guides associés

Comprendre le workflow sous un autre angle.