En bref
Les conflits de synchronisation SwaggerHub surviennent lorsque des modifications concurrentes ou l'intégration Git créent des versions de spécification contradictoires. La résolution implique l'identification des versions en conflit, la fusion manuelle des modifications et une nouvelle soumission. La prévention est préférable à la résolution — une propriété claire, une discipline des branches et des conventions de verrouillage réduisent la plupart des conflits avant qu'ils ne se produisent. Le modèle de branchement d'Apidog réduit les conflits d'édition concurrents par conception.
Introduction
Les fonctionnalités d'édition collaborative de SwaggerHub sont réellement utiles. Plusieurs membres de l'équipe peuvent travailler sur la même définition d'API, les modifications sont visibles presque en temps réel, et l'intégration Git permet aux équipes de maintenir les spécifications synchronisées avec leurs dépôts sources.
Mais la collaboration introduit des conflits. Deux ingénieurs modifient le même point de terminaison simultanément. Une spécification est mise à jour dans SwaggerHub et séparément dans GitHub, et le processus de synchronisation rencontre des versions divergentes. Un domaine est mis à jour pendant qu'une API est en cours de révision. Ces conflits sont gérables, mais ils sont perturbateurs lorsqu'ils se produisent de manière inattendue et que les équipes n'ont pas de processus de résolution clair.
Ce guide explique les types de conflits qui se produisent dans SwaggerHub, comment résoudre chaque type, et comment les prévenir avec une meilleure discipline de travail. La dernière section explique comment l'approche d'Apidog gère la même catégorie de problèmes.
Types de conflits de synchronisation dans SwaggerHub
1. Conflits d'édition concurrente. SwaggerHub permet à plusieurs utilisateurs de modifier une définition d'API en même temps. Lorsque deux utilisateurs modifient simultanément la même section de la spécification, la dernière sauvegarde l'emporte. Il n'y a pas de fusion — la seconde sauvegarde écrase les modifications du premier utilisateur. Ce n'est techniquement pas un "conflit" au sens de Git (il n'y a pas d'état d'erreur), mais cela entraîne une perte de données si les équipes ne sont pas prudentes.
2. Conflits de synchronisation SwaggerHub vers Git. SwaggerHub s'intègre avec GitHub, GitLab et Bitbucket. Lorsqu'une spécification est enregistrée dans SwaggerHub, elle peut être automatiquement poussée vers un dépôt configuré. Lorsqu'un fichier de spécification est directement validé dans le dépôt, il peut être synchronisé de nouveau avec SwaggerHub. Si les deux se produisent indépendamment, vous obtenez des versions contradictoires que le processus de synchronisation de SwaggerHub ne peut pas réconcilier automatiquement.
3. Conflits de branchement de version API. Lorsque vous créez une branche d'une version d'API dans SwaggerHub pour créer une nouvelle branche de travail, puis que vous tentez de fusionner les modifications, les différences entre la branche et l'originale peuvent créer des conflits nécessitant une résolution manuelle.
4. Conflits d'incompatibilité de version de domaine. Si une API référence un domaine SwaggerHub à une version spécifique, et que cette version de domaine est obsolète ou modifiée de manière incompatible, l'API de référence peut rencontrer des erreurs de résolution. Ce n'est pas un conflit de synchronisation en soi, mais cela provoque une perturbation similaire et nécessite des étapes de résolution similaires.
5. Conflits de "Git pull" dans les dépôts connectés. Lorsque le dépôt Git connecté à SwaggerHub a des branches ou des fusions qui entraînent des conflits dans le fichier de spécification, le processus de synchronisation de SwaggerHub signalera ces conflits lors de la prochaine synchronisation.
Résolution des conflits d'édition concurrente
Ce type de "conflit" est le plus courant et le plus invisible. Il n'y a pas de message d'erreur — les modifications d'un utilisateur disparaissent simplement.
Résolution :
- Si vous remarquez que des modifications sont manquantes après qu'un autre membre de l'équipe a enregistré, vérifiez l'historique des modifications de SwaggerHub (si disponible sur votre plan) pour voir ce qui a été écrasé.
- Demandez au membre de l'équipe qui a enregistré en dernier de comparer l'état actuel de la spécification avec sa copie locale.
- Saisissez manuellement les modifications manquantes.
La prévention est la seule vraie solution. Voir la section prévention ci-dessous.
Résolution des conflits de synchronisation SwaggerHub vers Git
Lorsque SwaggerHub et votre dépôt Git ont divergé, vous verrez généralement une erreur de synchronisation dans le panneau d'intégration Git de SwaggerHub indiquant qu'il ne peut pas effectuer un "auto-push" car le dépôt distant contient des modifications qui ne sont pas dans la version de SwaggerHub.
Étapes de résolution :
Étape 1 : Tirez la spécification actuelle de votre dépôt Git. Téléchargez le fichier YAML ou JSON de la branche qui cause le conflit.
Étape 2 : Tirez la spécification actuelle de SwaggerHub. Exportez l'API au format YAML depuis SwaggerHub.
Étape 3 : Comparez les deux fichiers. Utilisez n'importe quel outil de comparaison (diff, la vue de comparaison de VS Code ou un outil de comparaison compatible OpenAPI). Identifiez les modifications qui existent dans Git et qui ne sont pas dans SwaggerHub, et vice versa.
Étape 4 : Fusionnez manuellement. Créez une version réconciliée de la spécification qui inclut les deux ensembles de modifications. Cela nécessite un jugement humain — un outil de fusion automatisé peut produire un YAML syntaxiquement valide mais sémantiquement incorrect.
Étape 5 : Choisissez une source unique de vérité. Décidez si SwaggerHub ou Git est la source faisant autorité, puis mettez à jour l'autre. Si Git est l'autorité, validez la spécification fusionnée dans le dépôt et laissez la synchronisation la récupérer dans SwaggerHub. Si SwaggerHub est l'autorité, poussez la spécification fusionnée de SwaggerHub vers Git.
Étape 6 : Vérifiez la synchronisation. Après la mise à jour, confirmez que le panneau d'intégration Git de SwaggerHub affiche un état de synchronisation propre, sans conflits.
Un outil utile : openapi-diff. Plusieurs outils de comparaison OpenAPI comparent les versions de spécification à un niveau sémantique (ajouts de points de terminaison, modifications de champs, changements majeurs ou non) plutôt que ligne par ligne. Des outils comme oasdiff ou openapi-diff offrent une sortie plus claire qu'une comparaison YAML brute.
Résolution des conflits d'incompatibilité de version de domaine
Si votre API référence une version de domaine qui a été modifiée ou dépréciée :
Étape 1 : Identifiez la version de domaine que votre API référence. Regardez les URLs $ref dans votre spécification — elles incluent le numéro de version.
Étape 2 : Examinez le journal des modifications pour la version du domaine. Vérifiez ce qui a changé entre votre version épinglée actuelle et la dernière version.
Étape 3 : Évaluez si les modifications sont majeures. L'ajout de nouveaux champs optionnels n'est pas majeur. La suppression de champs, la modification de types ou le renommage de propriétés sont des modifications majeures.
Étape 4 : Mettez à jour les chemins $ref de votre API pour référencer la nouvelle version du domaine si vous décidez de migrer. Testez que la spécification valide toujours correctement après la mise à jour.
Étape 5 : Mettez l'équipe à jour. Si le changement de domaine affecte plusieurs API, coordonnez la migration afin que toutes les équipes mettent à jour selon le même calendrier.
Résolution des conflits de branchement de version d'API
Lors de la fusion d'une version d'API branchée vers la version principale :
Étape 1 : Exportez la branche et la version principale sous forme de fichiers YAML.
Étape 2 : Comparez les deux spécifications à l'aide d'un outil de comparaison OpenAPI.
Étape 3 : Dans l'éditeur SwaggerHub, appliquez manuellement les modifications de la branche à la version principale (ou vice versa, selon l'état final souhaité).
Étape 4 : Validez la spécification fusionnée dans l'éditeur de SwaggerHub pour confirmer l'absence d'erreurs de validation.
Étape 5 : Supprimez ou archivez la branche si elle n'est plus nécessaire.
Prévention : réduire les conflits avant qu'ils ne se produisent
Établir des zones de propriété claires. Attribuez différentes sections d'une spécification d'API volumineuse à différents membres de l'équipe. Une personne gère les points de terminaison d'authentification, une autre les points de terminaison de ressource. Les zones d'édition qui se chevauchent sont là où se produisent les conflits concurrents.
Utiliser le branchement pour les changements non triviaux. Pour tout changement qui prendra plus d'une heure ou nécessitera une révision, créez une branche de la version de l'API avant de modifier. Cela isole votre travail de la version principale jusqu'à ce que vous soyez prêt à fusionner.
Établir un protocole de synchronisation Git. Si vous utilisez l'intégration Git, décidez et documentez quelle direction fait autorité. "SwaggerHub est l'éditeur ; Git est l'enregistrement" ou "Git est la source de vérité ; SwaggerHub se synchronise à partir de celui-ci" — pas les deux simultanément avec des modifications indépendantes de chaque côté.
Communiquer avant de modifier des zones partagées. Utilisez Slack, un système de tickets ou la fonction de commentaires de SwaggerHub pour signaler que vous êtes sur le point de modifier une section que d'autres pourraient également avoir besoin de toucher. Une communication asynchrone prévient la plupart des écrasements d'éditions concurrentes.
Épingler explicitement les références de domaine. Référencez toujours une version de domaine spécifique dans vos chemins $ref, et non une référence flottante "dernière". Cela empêche les modifications majeures automatiques de se propager dans votre API sans action délibérée.
Définir les paramètres d'auto-push avec soin. La fonction d'auto-push à la sauvegarde de SwaggerHub peut être pratique mais crée un risque de conflit si les membres de l'équipe s'engagent également à modifier la spécification directement dans le dépôt Git. Désactivez l'auto-push si des développeurs effectuent des modifications de spécification aux deux endroits.
Comment Apidog gère les mêmes problèmes
Le modèle de collaboration d'Apidog est basé sur le branchement de style Git, ce qui prévient la plupart de ces schémas de conflits par conception.
Pas d'écrasement concurrent. Dans Apidog, les membres de l'équipe travaillent sur des branches séparées. Un ingénieur créant un nouveau point de terminaison crée une branche, effectue le travail et ouvre une demande de révision une fois terminé. Un autre ingénieur apportant une modification différente fait de même sur une branche séparée. Les modifications ne fusionnent pas avec la branche principale tant qu'elles n'ont pas été examinées et approuvées. Cela élimine complètement le problème d'écrasement "la dernière sauvegarde l'emporte".
Porte de révision intégrée. Le flux de travail de révision et d'approbation signifie que les modifications de spécification passent par une étape de vérification explicite avant d'affecter la branche principale ou la documentation utilisée par les équipes en aval.
Détection des conflits lors de la fusion. Lorsque deux branches modifient le même point de terminaison ou schéma, le processus de fusion d'Apidog signale explicitement le conflit. L'équipe le résout avec une vue claire des deux ensembles de modifications.
Flux de travail local d'abord. Pour les équipes préoccupées par les conflits de synchronisation avec les dépôts Git externes, le flux de travail local d'Apidog réduit le rayon d'impact — les modifications sont validées dans la plateforme avant d'être validées dans Git.
FAQ
Existe-t-il une interface utilisateur de résolution de conflits intégrée dans SwaggerHub ? SwaggerHub ne dispose pas d'une interface graphique de résolution de conflits de fusion comme certains outils Git GUI. La résolution des conflits est manuelle — téléchargez les deux versions, comparez-les en dehors de SwaggerHub, et téléchargez la version résolue.
Quel est le meilleur outil de comparaison OpenAPI à utiliser lors de la résolution des conflits ? oasdiff est un outil en ligne de commande bien entretenu qui produit des comparaisons structurées des spécifications OpenAPI, signalant les changements majeurs séparément des ajouts non majeurs. C'est une sortie plus utile qu'une comparaison YAML brute pour le travail de spécification d'API.
Puis-je verrouiller une API dans SwaggerHub pour empêcher d'autres personnes de la modifier ? SwaggerHub ne dispose pas d'un mécanisme de verrouillage de fichiers intégré. La solution la plus proche consiste à utiliser le système de rôles de SwaggerHub pour restreindre temporairement les autorisations de modification pendant que vous effectuez des changements, puis à les restaurer.
Comment savoir quelle version d'une API en conflit est correcte ? Vérifiez le journal d'activité de SwaggerHub (si votre plan l'inclut) pour voir qui a effectué quelles modifications et quand. Si vous utilisez Git, l'historique des commits est un enregistrement fiable. Si ni l'un ni l'autre n'est concluant, consultez les membres de l'équipe impliqués pour reconstituer l'intention.
SwaggerHub me notifie-t-il lorsqu'un domaine dont je dépendais est mis à jour ? SwaggerHub peut vous notifier des mises à jour de domaine via son système de notification. La configuration de cette fonctionnalité dépend de vos paramètres de notification. Vérifiez les paramètres de l'organisation > Notifications pour configurer les alertes concernant les modifications de domaine.
La migration vers Apidog prévient-elle tous les conflits de synchronisation ? Le branchement réduit considérablement la fréquence des conflits, mais ne les élimine pas complètement. Deux branches qui modifient le même point de terminaison doivent toujours être réconciliées lors de la fusion. Ce que le branchement fait, c'est rendre ces conflits visibles et explicites plutôt que des écrasements silencieux.
Les conflits de synchronisation dans SwaggerHub sont principalement un problème de flux de travail, et non un problème de produit. Une propriété claire, une discipline des branches et un protocole de synchronisation Git défini préviennent la plupart des problèmes avant qu'ils ne surviennent. Lorsque des conflits se produisent, un processus méthodique — exporter les deux versions, les comparer avec un outil approprié, fusionner manuellement, valider et vérifier la synchronisation — les résout de manière fiable. Le modèle de branchement d'Apidog réduit la fréquence des conflits en rendant le travail parallèle explicite, mais tout outil d'édition collaborative bénéficie de la même discipline sous-jacente.