DEV Community

Cover image for Meilleurs outils CLI légers pour la collaboration API
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Meilleurs outils CLI légers pour la collaboration API

La collaboration API impliquait auparavant d’ouvrir une application lourde, d’attendre la synchronisation, puis de parcourir des panneaux pour comprendre les modifications d’un coéquipier. Avec une spécification OpenAPI, l’essentiel du travail est textuel : versionner la spécification, relire un diff et fusionner un changement partagé. Ces opérations peuvent rester dans le terminal.

Essayez Apidog dès aujourd’hui

Ce guide présente des outils CLI légers pour couvrir ces trois tâches. Ils s’installent rapidement, s’exécutent avec une commande et s’intègrent à Git ou à la CI. Pour une vue plus large des workflows d’équipe, consultez les outils de collaboration API ; cet article se concentre sur le terminal.

Le workflow se découpe en trois étapes :

  1. Versionner la spécification : savoir qui a modifié quelle version.
  2. Réviser le changement : identifier les différences et les ruptures potentielles.
  3. Partager et fusionner : intégrer le travail dans une source de vérité commune.

Tous les outils ci-dessous lisent ou produisent des spécifications basées sur le standard OpenAPI.

Qu’est-ce qu’un outil CLI « léger » pour la collaboration API ?

Un outil est réellement léger s’il respecte la plupart de ces critères :

  • Installation minimale : un binaire, une commande npx ou un npm install -g.
  • Exécution ponctuelle : il démarre, produit un résultat, puis se termine. Vous pouvez l’appeler dans un script ou un hook Git.
  • Configuration réduite : il accepte un fichier openapi.yaml avec peu ou pas de configuration.
  • Sortie exploitable dans le terminal : lisible localement ou redirigeable vers la CI.
  • Responsabilité ciblée : diff, publication, lint ou fusion, sans imposer une plateforme complète.

Les outils suivants vont du plus local au plus intégré.

1. Git + un fichier de spécification : la base

Le point de départ est Git. Placez votre fichier OpenAPI dans le dépôt, à côté du code applicatif. Vous obtenez immédiatement l’historique, les branches, les pull requests et les revues de code.

# Ajouter la spécification au dépôt
git add openapi.yaml
git commit -m "Ajouter des paramètres de pagination à GET /orders"

# Examiner les changements par rapport à main
git diff main -- openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dans une pull request, les relecteurs peuvent commenter les lignes modifiées de openapi.yaml, puis la fusion devient le changement partagé. C’est le principe de la collaboration API Git-native.

Idéal pour : l’historique et la revue sans ajouter d’outil.

Limite : un diff Git brut sur YAML peut être bruyant. Un réordonnancement de clés ou une réindentation peut apparaître comme une modification alors que le contrat API est inchangé. Ajoutez un diff sémantique pour détecter les changements réels.

2. oasdiff : bloquer les changements cassants

oasdiff compare deux spécifications OpenAPI et détecte les changements cassants. C’est un binaire Go open source sous licence Apache 2.0, adapté aux contrôles CI.

# Installation sur macOS
brew install oasdiff

# Échouer si la nouvelle spécification casse les clients existants
oasdiff breaking main-spec.yaml pr-spec.yaml

# Code de sortie :
# 0 = aucun changement cassant
# 1 = changements cassants détectés
Enter fullscreen mode Exit fullscreen mode

Ajoutez cette commande à votre pipeline CI avant la fusion :

# Exemple GitHub Actions
- name: Vérifier les changements OpenAPI cassants
  run: oasdiff breaking main-spec.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Pour générer un résumé lisible de tous les changements :

oasdiff changelog base.yaml revision.yaml
Enter fullscreen mode Exit fullscreen mode

Idéal pour : protéger main contre les ruptures de contrat.

Limite : oasdiff compare et rapporte ; il ne publie pas de documentation et ne gère pas les branches.

3. Optic : réviser les changements OpenAPI dans une PR

Optic est un CLI Node.js sous licence MIT. Il compare, linte et révise les modifications OpenAPI en tenant compte des workflows Git. Il gère notamment $ref, oneOf et allOf, qui compliquent les comparaisons naïves.

# Installation
npm install -g @useoptic/optic

# Comparer la spécification courante à la branche main
optic diff openapi.yaml --base main --check
Enter fullscreen mode Exit fullscreen mode

Utilisez-le dans une PR pour produire une revue centrée sur le contrat API plutôt que sur les seules lignes YAML modifiées.

Idéal pour : une revue structurée des changements API avec des règles de validation.

Limite : basé sur Node.js, il est plus lourd qu’un binaire unique. Son intérêt augmente si vous adoptez sa configuration et ses règles.

4. CLI Bump.sh : publier et comparer la documentation

Le CLI Bump.sh permet de publier une documentation API et de comparer une spécification locale avec une version déjà publiée. Le flux de collaboration repose ici sur une référence partagée et à jour.

# Installation
npm install -g bump-cli

# Publier une nouvelle version de la documentation
bump deploy openapi.yaml --doc my-api --token $BUMP_TOKEN

# Obtenir le journal des changements par rapport à la version publiée
bump diff openapi.yaml --doc my-api
Enter fullscreen mode Exit fullscreen mode

Vous pouvez, par exemple, ajouter la sortie de bump diff dans le corps d’une pull request.

Idéal pour : synchroniser une documentation lisible par les équipes et les consommateurs de l’API.

Limite : l’hébergement de documentation et le flux de déploiement font partie de l’offre Bump.sh. Le CLI est le client local de cette plateforme.

5. Redocly CLI : lint, bundle et registre partagé

Redocly CLI fournit des commandes pour linter, regrouper et publier des spécifications. Le bundle est particulièrement utile pour transformer une spécification répartie dans plusieurs fichiers et références $ref en un artefact unique.

# Linter une spécification sans installation globale
npx @redocly/cli lint openapi.yaml

# Regrouper les fichiers OpenAPI dans un seul fichier
npx @redocly/cli bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Pour publier une version dans le registre partagé Redocly :

# Nécessite une clé API
npx @redocly/cli push openapi.yaml \
  --organization "Acme" \
  --project "orders-api"
Enter fullscreen mode Exit fullscreen mode

Idéal pour : appliquer un style OpenAPI interne, produire un bundle propre et publier une source de vérité dans un registre.

Limite : lint et bundle sont locaux, mais push et le registre font partie de la plateforme hébergée Redocly. Pour des workflows d’édition plus poussés, consultez ce guide sur la collaboration pour l’édition de spécifications API.

6. GitHub CLI (gh) : gérer la revue et la fusion

Si votre équipe utilise GitHub, le CLI GitHub permet de gérer la pull request sans quitter le shell.

# Créer une PR pour la modification de spécification
gh pr create \
  --title "Ajouter la pagination /orders" \
  --body "Ajoute les paramètres page + limit"

# Approuver une PR
gh pr review --approve
Enter fullscreen mode Exit fullscreen mode

Combinez gh avec oasdiff ou Optic dans votre CI : gh pilote la discussion et la fusion, tandis que l’outil de diff vérifie la sémantique de l’API.

Idéal pour : créer, suivre et approuver les pull requests depuis le terminal.

Limite : gh ne sait pas si une modification OpenAPI est cassante. Ajoutez oasdiff ou Optic pour ce contrôle.

7. CLI Apidog : branches, revue et fusion dans un seul CLI

Le CLI Apidog est plus intégré que les outils précédents. Il donne accès depuis le terminal aux ressources de projet, au versionnement et aux flux de collaboration de la plateforme Apidog.

Les groupes de commandes importants sont :

  • branch : créer et gérer des branches de spécification ;
  • merge-request : soumettre des changements à la revue ;
  • git-connection : sauvegarder les spécifications dans un dépôt Git. 
# Installer et s’authentifier
npm install -g apidog-cli
apidog login --with-token $APIDOG_TOKEN

# Créer une branche isolée pour une fonctionnalité
apidog branch create --type sprint --name "orders-pagination"
Enter fullscreen mode Exit fullscreen mode

L’option --type sélectionne le modèle de branche :

  • sprint pour une fonctionnalité ou une release limitée ;
  • general pour le travail continu ;
  • ai pour une branche isolée utilisée par un agent.

Lorsque le changement est prêt, créez une demande de fusion plutôt que de fusionner directement :

# Soumettre les endpoints modifiés à la revue
apidog merge-request create \
  --branch "orders-pagination" \
  --endpoint-ids 1,2
Enter fullscreen mode Exit fullscreen mode

Pour connecter les spécifications du projet à un dépôt Git :

apidog git-connection --help
Enter fullscreen mode Exit fullscreen mode

Le CLI produit une sortie JSON structurée, incluant agentHints.nextSteps, ce qui facilite son appel depuis des scripts ou des agents IA. Consultez le guide complet du CLI Apidog pour les commandes disponibles.

Idéal pour : centraliser versionnement, revue et fusion dans un même workflow CLI.

Limite : il s’agit d’un CLI de plateforme : il communique avec un projet Apidog, plutôt qu’avec un simple fichier local. Il ne fournit pas de linter OpenAPI ; utilisez Redocly ou Spectral pour les règles de style. Pour ajouter une gestion des accès basée sur les rôles, consultez la collaboration API sécurisée avec RBAC.

Comment choisir

Choisissez l’outil selon la tâche à automatiser.

Outil Idéal pour Installation Open source ? Notes
Git + fichier de spécification Historique et revue sans nouvel outil Déjà installé Oui (Git) Bruyant sur YAML ; à combiner avec un diff sémantique
oasdiff Porte de fusion pour les changements cassants brew install oasdiff Oui (Apache 2.0) Le code de sortie peut faire échouer la CI
Optic Revue structurée dans les PR npm i -g @useoptic/optic Oui (MIT) Gère $ref, oneOf, allOf, etc.
CLI Bump.sh Documentation partagée et diffs npm i -g bump-cli CLI ouvert, hébergement payant Node 20+ ; diff et preview ne nécessitent pas de jeton
Redocly CLI Lint, bundle, publication dans un registre npx @redocly/cli CLI ouvert, registre payant push nécessite une clé API
GitHub CLI Pilotage des PR depuis le shell brew install gh Oui (MIT) Gère la PR, pas la sémantique API
CLI Apidog Versionnement, revue et fusion intégrés npm i -g apidog-cli Non, niveau gratuit disponible branch, merge-request, git-connection

Dans la pratique, la plupart des équipes combinent plusieurs outils :

  1. Commiter openapi.yaml dans Git.
  2. Exécuter oasdiff ou Optic dans la CI.
  3. Utiliser gh pour créer et suivre les pull requests.
  4. Publier la documentation avec Bump.sh ou Redocly.

Si vous préférez gérer les branches, la revue et la fusion depuis un seul CLI, Apidog couvre ces trois étapes. Pour comparer les approches plus largement, consultez ce guide des outils d’équipe pour la collaboration API.

En résumé

Une collaboration API efficace depuis le terminal suit trois étapes : versionner la spécification, réviser le diff, puis fusionner le changement partagé.

  • Git gère l’historique et les branches.
  • oasdiff et Optic vérifient les changements API.
  • Bump.sh et Redocly publient ou partagent la documentation.
  • GitHub CLI pilote la pull request.
  • Le CLI Apidog réunit versionnement, revue et fusion dans un seul ensemble de commandes.

Vous voulez un workflow intégré sans assembler plusieurs outils ? Téléchargez Apidog, installez apidog-cli, puis lancez vos premières commandes apidog branch create et apidog merge-request depuis votre terminal.

Top comments (1)

Collapse
 
topstar_ai profile image
Luis Cruz •

Je trouve l'idée d'utiliser des outils CLI légers pour la collaboration API vraiment intéressante, notamment pour améliorer la productivité et la simplicité dans les workflows d'équipe. La mention d'oasdiff pour détecter les changements cassants dans les spécifications OpenAPI me semble particulièrement utile, car cela peut aider à éviter les problèmes de compatibilité lors des mises à jour de l'API. J'ai personnellement utilisé des outils similaires pour la revue de code et la gestion des versions, et je peux voir comment ces outils CLI pourraient simplifier ces processus. Pouvez-vous partager un exemple de comment oasdiff a été intégré dans un pipeline CI/CD pour automatiser la vérification des changements cassants ?