DEV Community

Cover image for Comment concevoir des API en ligne de commande
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment concevoir des API en ligne de commande

La plupart des tutoriels de conception d’API commencent avec une souris : ouvrir un éditeur visuel, faire glisser un schéma sur une toile, puis ajouter des champs dans des boîtes de dialogue. Cela fonctionne, mais ce flux ne correspond pas à la manière dont de nombreuses équipes livrent réellement. Si votre définition d’API est dans Git, révisée dans des pull requests et exécutée en intégration continue, concevez-la comme vous la déployez : depuis le terminal, en texte, avec des commandes scriptables.

Essayez Apidog dès aujourd’hui

Concevoir une API depuis la ligne de commande consiste à rédiger le contrat, le vérifier avec un linter, le regrouper dans un fichier autonome et générer des stubs, sans quitter le shell. Chaque étape est reproductible, automatisable dans un pipeline CI et facile à rejouer par un collègue ou un agent IA.

Ce guide présente deux approches :

  1. Une pile open source composée d’outils spécialisés : OpenAPI, Spectral, Redocly CLI et openapi-generator.
  2. La CLI Apidog, qui centralise schémas, endpoints et authentification dans un projet pilotable depuis le terminal.

Pour approfondir les principes de conception, consultez aussi le guide sur la conception d’une API et le tutoriel sur la conception d’API REST.

Si vous utilisez Apidog, installez d’abord le binaire. Le guide d’installation de la CLI Apidog couvre npm install -g apidog-cli et l’authentification avec apidog login --with-token. Le guide complet de la CLI détaille les groupes de commandes disponibles.

L’approche open source : rédaction, linting, regroupement, génération

La pile CLI classique assemble plusieurs outils indépendants. Vous versionnez votre définition OpenAPI, puis exécutez chaque outil dans une étape distincte. C’est le principe d’un flux de conception d’API natif Git.

1. Rédiger le document OpenAPI

Commencez avec un fichier YAML. Aucun éditeur spécialisé n’est nécessaire : un simple éditeur de texte suffit.

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, shipped, delivered]
Enter fullscreen mode Exit fullscreen mode

Quand l’API grandit, répartissez la spécification en plusieurs fichiers avec $ref. Vous gardez ainsi les schémas lisibles et faciles à réviser indépendamment.

2. Linter avec Spectral

Une spécification écrite à la main dérive vite : operationId oublié, réponse non documentée ou convention de nommage incohérente. Un linter détecte ces problèmes avant la revue de code.

Installez Spectral :

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectral affiche les violations avec leur ligne et leur gravité. Dans un pipeline CI, son code de sortie permet de faire échouer le build en présence d’erreurs.

Vous pouvez aussi utiliser vacuum, ou redocly lint. Quel que soit l’outil choisi, conservez cette étape séparée : le linting est une vérification dédiée.

3. Regrouper avec Redocly CLI

Une spécification divisée en plusieurs fichiers est pratique pour l’équipe, mais les générateurs et outils de publication attendent souvent un document unique.

Utilisez Redocly CLI pour résoudre les $ref et produire un fichier autonome :

npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Redocly peut aussi effectuer le linting avec redocly lint et prévisualiser des documents. Consultez la documentation officielle de Redocly CLI pour les commandes disponibles.

4. Générer des stubs avec openapi-generator

Une fois la spécification nettoyée et regroupée, générez du code serveur ou client.

npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Remplacez -g spring par un générateur pris en charge, par exemple :

  • python-flask
  • go-server
  • un générateur de SDK client compatible avec votre langage

Vous obtenez un échafaudage aligné sur le contrat OpenAPI.

Cette approche est entièrement ouverte et scriptable : quatre outils, quatre commandes. En contrepartie, vous maintenez l’organisation des fichiers, les règles de linting, le regroupement et la configuration de génération.

L’approche Apidog CLI : concevoir dans un projet unique

L’autre approche consiste à gérer schémas, endpoints, maquettes et authentification dans un seul projet, tout en gardant le terminal comme interface principale.

Le binaire apidog-cli fournit des commandes pour les ressources de conception :

  • schema pour les modèles de données ;
  • endpoint pour les opérations ;
  • folder pour l’organisation ;
  • security-scheme pour l’authentification ;
  • import, export et mock.

Point important : Apidog ne remplace pas un linter OpenAPI. Il ne vérifie pas l’application d’un guide de style ni les violations de règles OpenAPI. Gardez Spectral ou vacuum dans votre pipeline si vous avez besoin de linting. Apidog n’est pas non plus open source : c’est un produit commercial avec un niveau gratuit. Son intérêt est de réduire l’assemblage manuel des ressources de conception.

Le guide sur les alternatives à Swagger pour la conception et les tests d’API aide à évaluer ce compromis.

Installez ensuite la CLI et authentifiez-vous :

npm install -g apidog-cli
apidog login --with-token <VOTRE_TOKEN_D'ACCÈS>
Enter fullscreen mode Exit fullscreen mode

Les commandes renvoient du JSON structuré. La plupart des réponses incluent aussi agentHints.nextSteps, qui indique les prochaines commandes à exécuter. Utilisez --help sur chaque groupe de commandes pour afficher les options exactes.

Définir des modèles avec apidog schema

Commencez par les données. Un schéma réutilisable Order devient la source de vérité pour les endpoints qui y font référence, comme components/schemas dans une spécification OpenAPI.

apidog schema --help
apidog schema create --project <ID_DU_PROJET>
Enter fullscreen mode Exit fullscreen mode

Comme la sortie est du JSON, vous pouvez récupérer les identifiants avec jq et les transmettre à la commande suivante.

Si vous possédez déjà une spécification OpenAPI, importez-la plutôt que de recréer chaque ressource :

apidog import --project <ID_DU_PROJET> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog import accepte les formats OpenAPI 3.x, Swagger 2.0, Postman et Apidog.

Définir des endpoints avec apidog endpoint

Après les schémas, créez les opérations et rattachez-les aux ressources du projet.

apidog endpoint --help
apidog endpoint list --project <ID_DU_PROJET>
apidog endpoint create --project <ID_DU_PROJET>
Enter fullscreen mode Exit fullscreen mode

La commande list est utile dans un script : vous pouvez comparer les endpoints entre branches ou vérifier que chaque chemin possède les réponses attendues.

Utilisez folder pour regrouper les endpoints liés et conserver un projet navigable à mesure qu’il évolue.

Définir l’authentification avec apidog security-scheme

L’authentification fait partie du contrat. Le groupe security-scheme permet de définir des clés API, jetons porteurs, mécanismes OAuth 2.0 et autres schémas d’authentification.

apidog security-scheme --help
apidog security-scheme list --project <ID_DU_PROJET>
Enter fullscreen mode Exit fullscreen mode

Définissez le schéma une fois au niveau du projet, puis référencez-le dans les endpoints concernés. Cela évite de redéclarer l’authentification opération par opération et limite les dérives du contrat.

Valider les écritures avec apidog cli-schema validate

Avant de pousser des modifications ou de lancer une CI, vérifiez que vos fichiers de définition de ressources sont correctement structurés.

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

Ajoutez cette commande comme garde-fou dans le pipeline :

  1. valider le fichier de ressource ;
  2. appliquer les modifications seulement si la validation réussit.

Cette commande valide la structure attendue par la CLI. Elle ne remplace pas le linting OpenAPI : utilisez toujours Spectral ou vacuum pour les règles de style.

Exporter vers OpenAPI

Vous pouvez concevoir dans Apidog, puis transmettre un artefact standard au reste de votre outillage.

apidog export --project <ID_DU_PROJET> --format openapi -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog export peut produire des formats OpenAPI, HTML, Markdown ou Postman.

Vous récupérez ainsi une spécification OpenAPI portable à envoyer vers :

  • Spectral pour le linting ;
  • openapi-generator pour les stubs ;
  • votre pipeline de documentation.

Les deux approches sont complémentaires : l’export sert de pont entre le projet Apidog et les outils open source.

Intégrer le flux dans la CI

Chaque commande possède une sortie texte et un code de sortie. Vous pouvez donc construire un pipeline minimal de vérification de conception :

# Échoue en cas de violation des règles de style.
spectral lint openapi.yaml

# Valide les écritures de ressources CLI avant leur application.
apidog cli-schema validate --file resource.json

# Produit un artefact autonome pour les étapes suivantes.
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

La sortie JSON d’Apidog et agentHints.nextSteps rendent également ce flux exploitable par un agent de codage IA : il peut lire le résultat structuré et exécuter l’étape suivante sans interagir avec une interface graphique.

Pièges courants

Les fichiers divisés cassent les outils en aval.

Les fichiers $ref sont adaptés à la maintenance humaine, mais pas toujours aux générateurs. Regroupez la définition avant de générer du code ou de publier la documentation :

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Attendre d’Apidog qu’il effectue le linting.

Apidog gère les ressources, mais n’applique pas de guide de style OpenAPI. Gardez Spectral ou vacuum dans la boucle. apidog cli-schema validate vérifie la structure des ressources, pas le style de votre spécification.

Modifier un projet vide sans importer l’existant.

Pour faire évoluer une API déjà définie, importez d’abord sa spécification source dans le projet :

apidog import --project <ID_DU_PROJET> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Définir l’authentification endpoint par endpoint.

Créez un security-scheme au niveau du projet et référencez-le. La duplication de l’authentification est une source fréquente de dérive.

En résumé

Concevoir une API depuis la ligne de commande transforme une suite de clics en commandes répétables.

L’approche open source — rédaction OpenAPI, linting Spectral, regroupement Redocly et génération avec openapi-generator — offre un contrôle complet et évite toute dépendance propriétaire.

La CLI Apidog propose un projet intégré pour gérer schémas, endpoints et authentification depuis le terminal, avec des réponses JSON adaptées aux scripts et aux agents. L’export OpenAPI vous permet ensuite de réintégrer les outils standards de votre chaîne.

Choisissez selon votre contexte. Si vous travaillez déjà dans Git avec des outils spécialisés, gardez cette pile et utilisez apidog export lorsque vous avez besoin d’un artefact portable. Si vous préférez réduire l’assemblage manuel, téléchargez Apidog, installez la CLI et concevez votre prochaine API sans quitter le shell.

Top comments (0)