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 un nouveau commit. La prévention est préférable à la résolution — une propriété claire, la discipline des branches et les conventions de verrouillage réduisent la plupart des conflits avant qu'ils ne se produisent. Le modèle de ramification d'Apidog réduit les conflits d'édition concurrents par conception.
Introduction
Les fonctionnalités d'édition collaborative de SwaggerHub sont véritablement utiles. Plusieurs membres d'équipe peuvent travailler sur la même définition d'API, les modifications sont visibles en temps quasi 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 surviennent dans SwaggerHub, comment résoudre chaque type et comment les prévenir avec une meilleure discipline de flux 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 la même section de la spécification simultanément, la dernière sauvegarde l'emporte. Il n'y a pas de fusion — la deuxième sauvegarde écrase les modifications du premier utilisateur. Ce n'est techniquement pas un "conflit" au sens 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 poussée automatiquement vers un dépôt configuré. Lorsqu'un fichier de spécification est commité directement dans le dépôt, il peut être synchronisé 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 fork de version d'API. Lorsque vous forkz une version d'API dans SwaggerHub pour créer une nouvelle branche de travail, puis que vous essayez de fusionner les modifications, les différences entre le fork et l'original peuvent créer des conflits qui nécessitent une résolution manuelle.
4. Conflits de version de domaine incompatibles. 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 pull Git 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 SwaggerHub mettra en évidence 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 véritable 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 pousser automatiquement car le dépôt distant contient des modifications qui ne sont pas dans la version de SwaggerHub.
Étapes de résolution :
Étape 1 : Récupérez 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 : Récupérez 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 présentes dans Git 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 du 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 fait autorité, commitez la spécification fusionnée dans le dépôt et laissez la synchronisation la tirer vers SwaggerHub. Si SwaggerHub fait 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 au 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 fournissent une sortie plus claire qu'un simple diff YAML brut.
Résolution des conflits de versions de domaine incompatibles
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 du domaine que votre API référence. Regardez les URL $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 facultatifs 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 est toujours validée correctement après la mise à jour.
Étape 5 : Mettez à jour l'équipe. Si la modification du domaine affecte plusieurs API, coordonnez la migration afin que toutes les équipes effectuent la mise à jour selon le même calendrier.
Résolution des conflits de fork de version d'API
Lors de la fusion d'une version d'API forkée dans la version principale :
Étape 1 : Exportez la version forkée et la version principale en tant que 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 du fork à 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 qu'il n'y a pas d'erreurs de validation.
Étape 5 : Supprimez ou archivez le fork s'il n'est plus nécessaire.
Prévention : réduire les conflits avant qu'ils ne se produisent
Établissez 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 possède les points de terminaison d'authentification, une autre les points de terminaison de ressources. Les zones d'édition qui se chevauchent sont les endroits où se produisent les conflits concurrents.
Utilisez le forking pour les changements non triviaux. Pour toute modification qui prendra plus d'une heure ou nécessitera une révision, forkez la version de l'API avant de la modifier. Cela isole votre travail de la version principale jusqu'à ce que vous soyez prêt à fusionner.
Établissez 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 lui" — pas les deux simultanément avec des modifications indépendantes de chaque côté.
Communiquez avant de modifier des zones partagées. Utilisez Slack, un système de tickets ou la fonction de commentaire de SwaggerHub pour signaler lorsque vous êtes sur le point de modifier une section que d'autres pourraient également avoir besoin de toucher. La communication asynchrone prévient la plupart des écrasements d'éditions concurrentes.
Épinglez 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 "dernière" flottante. Cela empêche les changements majeurs automatiques de s'introduire dans votre API sans action délibérée.
Configurez les paramètres de push automatique avec soin. Le push automatique à l'enregistrement de SwaggerHub peut être pratique mais crée un risque de conflit si les membres de l'équipe committent également des modifications de spécification directement dans le dépôt Git. Désactivez le push automatique si vous avez des développeurs qui 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 une ramification de style Git, ce qui prévient la plupart de ces types de conflits par conception.
Pas d'écrasement concurrent. Dans Apidog, les membres de l'équipe travaillent sur des branches distinctes. 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 distincte. Les modifications ne sont fusionnées dans la branche principale qu'après révision et approbation. Cela élimine entièrement 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 de conflits lors de la fusion. Lorsque deux branches modifient le même point de terminaison ou le même 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 axé sur le local. 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 commises 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 maintenu 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'un simple diff YAML brut pour le travail sur les spécifications d'API.
Puis-je verrouiller une API dans SwaggerHub pour empêcher d'autres personnes de la modifier ? SwaggerHub ne dispose pas de mécanisme de verrouillage de fichier intégré. La solution de contournement 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 la bonne ? Vérifiez le journal d'activité de SwaggerHub (si votre plan l'inclut) pour voir qui a fait 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épends 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 pour les changements 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 entièrement. Deux branches qui modifient toutes deux le même point de terminaison doivent toujours être réconciliées lors de leur fusion. Ce que fait le branchement, 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, la 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 ramification 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.