La plupart des tutoriels de conception d'API commencent avec une souris. Ouvrez un éditeur visuel, faites glisser un schéma sur une toile, cliquez sur des boîtes de dialogue pour ajouter un champ. Cela fonctionne, mais cela ne correspond pas à la façon dont beaucoup d'équipes livrent réellement. Si votre définition d'API est dans Git, est révisée dans les pull requests et passe par l'intégration continue, vous voulez la concevoir de la même manière que vous la déployez : depuis le terminal, en texte, avec des commandes que vous pouvez scripter.
Concevoir des API depuis la ligne de commande signifie que vous rédigez le contrat, le linter par rapport à un guide de style, le regroupez dans un seul fichier et générez des stubs, le tout sans quitter le shell. Chaque étape est reproductible. Chaque étape peut s'exécuter dans un pipeline. Et lorsqu'un agent IA ou un coéquipier doit reproduire votre configuration, il exécute les mêmes commandes que vous avez utilisées au lieu de deviner sur quels boutons vous avez cliqué.
Ce guide présente deux approches. Premièrement, la voie open-source générale construite à partir d'outils à usage unique : rédiger un fichier OpenAPI, le linter avec Spectral, le regrouper avec l'interface de ligne de commande Redocly, et générer des stubs de serveur avec openapi-generator. Ensuite, la voie de l'interface de ligne de commande Apidog, où la conception, les schémas, les points de terminaison et l'authentification vivent dans un seul projet que vous pouvez piloter depuis le terminal. Si vous voulez d'abord le contexte conceptuel plus approfondi, lisez notre guide sur comment concevoir une API et le tutoriel sur la conception d'API REST.
Si vous suivez avec Apidog, procurez-vous d'abord le binaire. Notre guide d'installation de l'interface de ligne de commande Apidog couvre l'étape `npm install -g apidog-cli` et le "handshake" `apidog login --with-token`, et le guide complet de l'interface de ligne de commande Apidog détaille chaque groupe de commandes.
L'approche open-source générale : rédaction, linting, regroupement, génération
La pile de conception CLI classique est un ensemble d'outils indépendants que vous assemblez. Vous conservez votre définition d'API dans un fichier OpenAPI sous contrôle de version et exécutez chaque outil comme une étape. C'est le flux de travail de conception d'API natif Git, et il est vraiment bon. Voici sa structure.
Rédiger le document OpenAPI
Vous commencez par un simple fichier YAML. Aucun éditeur spécial n'est requis ; n'importe quel éditeur de texte fonctionne. Un `openapi.yaml` minimal ressemble à ceci :
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]
Au fur et à mesure que l'API grandit, vous la divisez en plusieurs fichiers et y faites référence avec `$ref`. Cela permet de garder chaque schéma lisible et révisable indépendamment.
Linter avec Spectral
Les fichiers OpenAPI écrits à la main peuvent dériver. Quelqu'un oublie un `operationId`, une autre personne laisse une réponse non documentée, une troisième invente sa propre convention de nommage. Un linter détecte tout cela avant la révision. Spectral, de Stoplight, est le choix standard. Il fournit des jeux de règles pour OpenAPI et vous permet d'écrire les vôtres.
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectral affiche chaque violation avec un numéro de ligne et une gravité. Vous pouvez faire échouer la compilation en cas d'erreurs en vérifiant le code de sortie dans l'intégration continue. L'interface de ligne de commande de Redocly et vacuum font le même travail si vous voulez une alternative ; vacuum est rapide et s'intègre comme un linter compatible Spectral. Le principe reste le même, quel que soit celui que vous choisissez : le linting est un outil séparé et dédié, et vous l'exécutez comme une étape à part entière.
Regrouper avec l'interface de ligne de commande Redocly
Une fois votre définition répartie sur plusieurs fichiers, la plupart des outils en aval souhaitent un document unique et autonome. L'interface de ligne de commande Redocly résout chaque `$ref` et aplatit l'arborescence en un seul fichier.
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redocly effectue également du linting (`redocly lint`) et prévisualise les documents, de sorte que certaines équipes l'utilisent à la fois pour la vérification de style et le regroupement. Sa documentation officielle liste l'ensemble complet des commandes.
Générer des stubs avec openapi-generator
Avec une spécification propre et regroupée, vous générez du code. openapi-generator transforme un document OpenAPI en stubs de serveur, SDK clients et plus encore dans des dizaines de langages.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
Remplacez `-g spring` par `-g python-flask`, `-g go-server`, ou n'importe quel générateur pris en charge. Vous disposez maintenant d'un échafaudage qui correspond exactement à votre contrat.
C'est l'approche ouverte de bout en bout : quatre outils, quatre commandes, tous scriptables. Le coût est l'assemblage. Vous maintenez vous-même l'agencement des fichiers, la configuration du linter, l'étape de regroupement et la configuration du générateur, et chaque outil a ses propres conventions. Cela fonctionne bien lorsque vous voulez un contrôle maximal et que l'intégration ne vous dérange pas.
L'approche de l'interface de ligne de commande Apidog : concevoir dans un seul projet
L'autre approche maintient la conception, les schémas, les points de terminaison, les maquettes et l'authentification au sein d'un seul projet que vous pilotez depuis le terminal. Le binaire `apidog-cli` est une interface de ligne de commande complète pour les ressources de projet, pas seulement un exécuteur de tests. Il dispose de groupes de commandes pour toute la surface de conception : `schema` pour les modèles de données, `endpoint` pour les opérations, `folder` pour l'organisation, `security-scheme` pour l'authentification, plus `import`, `export`, `mock`, et plus encore.
Une note honnête au préalable : Apidog ne lintera pas votre OpenAPI et n'appliquera pas de guide de style. Ce n'est pas son but. Si vous avez besoin de linting, gardez Spectral ou vacuum dans votre pipeline. Apidog n'est pas non plus open source ; c'est un produit commercial avec un niveau gratuit. Ce qu'il vous offre, c'est un projet intégré afin que vous n'ayez pas à assembler vous-même les pièces de conception. Notre avis sur les alternatives à Swagger pour la conception et les tests d'API explique quand ce compromis est pertinent.
Installez et authentifiez-vous d'abord (voir le guide d'installation pour la configuration du jeton) :
npm install -g apidog-cli
apidog login --with-token <VOTRE_TOKEN_D'ACCÈS>
Chaque commande renvoie du JSON structuré, et la plupart des réponses incluent un bloc `agentHints.nextSteps` qui vous indique (ou à un agent) ce qu'il faut exécuter ensuite. Ajoutez `--help` à n'importe quelle commande pour voir ses drapeaux exacts.
Définir des modèles de données avec `apidog schema`
La conception commence par vos données. Un schéma `Order` réutilisable devient la source unique de vérité à laquelle les points de terminaison font référence, la même idée que `components/schemas` dans un OpenAPI brut, mais géré comme une ressource de projet.
apidog schema --help
apidog schema create --project <ID_DU_PROJET>
Étant donné que la sortie est en JSON, vous pouvez la canaliser via `jq` pour récupérer l'ID du nouveau schéma et l'alimenter dans la commande suivante. Si vous avez déjà un fichier OpenAPI, importez-le au lieu de tout retaper :
apidog import --project <ID_DU_PROJET> --file openapi.yaml
`apidog import` accepte les formats OpenAPI 3.x, Swagger 2.0, Postman et Apidog, de sorte qu'une définition existante devient un projet actif en une seule étape.
Définir des points de terminaison avec `apidog endpoint`
Les modèles étant en place, vous ajoutez des opérations. Le groupe `endpoint` crée et met à jour des points de terminaison, les connectant aux schémas que vous avez définis et aux dossiers qui les organisent.
apidog endpoint --help
apidog endpoint list --project <ID_DU_PROJET>
apidog endpoint create --project <ID_DU_PROJET>
Lister les points de terminaison en JSON est utile en soi. Vous pouvez comparer la sortie entre les branches ou la fournir à un script qui vérifie que chaque chemin a les réponses que vous attendez. Regroupez les points de terminaison liés avec la commande `folder` pour que le projet reste navigable à mesure qu'il grandit.
Définir l'authentification avec `apidog security-scheme`
L'authentification fait partie du contrat, pas une réflexion après coup. Le groupe `security-scheme` définit comment les clients s'authentifient : clés API, jetons porteurs, OAuth 2.0, etc. Cela correspond à `components/securitySchemes` dans OpenAPI, donc l'importation et l'exportation se font proprement.
apidog security-scheme --help
apidog security-scheme list --project <ID_DU_PROJET>
Définir le schéma une seule fois au niveau du projet signifie que chaque point de terminaison peut s'y référer au lieu que chaque opération redéclare sa propre authentification. C'est exactement le genre de cohérence pour laquelle un linter vous reprocherait le manque.
Valider vos écritures avec `apidog cli-schema validate`
Avant de commettre des modifications ou de confier un projet à l'intégration continue, vous voulez vous assurer que vos définitions de ressources sont bien formées. L'interface de ligne de commande propose une commande `cli-schema validate` qui vérifie un fichier de définition par rapport au schéma attendu par l'interface de ligne de commande, de sorte qu'une écriture mal formée échoue rapidement au lieu de se répercuter silencieusement.
apidog cli-schema --help
apidog cli-schema validate --file resource.json
Exécutez cette étape comme une garde dans votre pipeline : validez d'abord, puis appliquez. Une sortie non nulle arrête le pipeline avant qu'une mauvaise ressource n'atteigne le projet. Il s'agit d'une validation de vos écritures CLI, et non d'un linting de style OpenAPI ; ce sont deux tâches différentes, et vous voulez toujours Spectral pour la seconde.
Exporter vers OpenAPI
Concevez dans Apidog, puis remettez un artefact standard au reste de votre chaîne d'outils. `apidog export` écrit en formats OpenAPI, HTML, Markdown ou Postman.
apidog export --project <ID_DU_PROJET> --format openapi -o dist/openapi.yaml
Vous êtes maintenant de retour à un fichier OpenAPI portable. Donnez-le à Spectral pour le linting, à openapi-generator pour les stubs, ou à votre build de documentation. Le projet intégré et la pile d'outils ouverts ne sont pas mutuellement exclusifs ; l'exportation est le pont entre eux.
Intégration dans l'intégration continue (CI)
Les deux approches brillent dans un pipeline car chaque commande a un code de sortie et une sortie texte. Une tâche minimale de vérification de conception pourrait exécuter le linter, puis valider, puis regrouper :
# échoue en cas de violations de style
spectral lint openapi.yaml
# valide toute écriture de ressource CLI avant application
apidog cli-schema validate --file resource.json
# aplatit en un seul artefact pour les étapes en aval
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Étant donné que la sortie d'Apidog est en JSON avec `agentHints.nextSteps`, ce flux est également piloté proprement par un agent de codage IA. L'agent lit le résultat structuré, voit l'étape suivante suggérée et l'exécute, sans avoir besoin de "screen-scraping" une interface graphique. C'est la raison principale pour concevoir à partir de l'interface de ligne de commande : ce qu'un humain tape, un script ou un agent peut aussi le taper.
Pièges courants
Les fichiers divisés cassent les outils en aval. Une définition répartie sur de nombreux fichiers `$ref` est excellente pour les humains et maladroite pour les générateurs. Regroupez toujours en un seul fichier avant de générer du code ou de publier des documents. `redocly bundle` est la solution.
Vous attendez d'Apidog qu'il effectue le linting. Ce ne sera pas le cas. Apidog gère les ressources ; il n'applique pas de guide de style et ne signale pas les violations des règles OpenAPI. Gardez Spectral ou vacuum dans la boucle pour cela. Confondre `apidog cli-schema validate` avec un linter est une erreur courante ; il valide la structure des ressources, pas le style OpenAPI.
Oublier d'importer avant d'éditer. Si vous modifiez une API existante via l'interface de ligne de commande, importez d'abord la définition source dans le projet. Modifier un projet vide et s'attendre à ce que vos anciens points de terminaison soient là est un moyen rapide de se tromper.
Authentification définie par point de terminaison au lieu d'une seule fois. Définissez un `security-scheme` au niveau du projet et faites-y référence. Redéclarer l'authentification sur chaque opération est une façon de laisser les contrats dériver.
En résumé
Concevoir des API depuis l'interface de ligne de commande transforme une tâche exigeant de nombreux clics en un ensemble de commandes répétables. L'approche ouverte – rédiger, linter avec Spectral, regrouper avec Redocly, générer avec openapi-generator – vous donne un contrôle total et aucune dépendance propriétaire. L'approche de l'interface de ligne de commande Apidog vous offre un projet intégré où les schémas, les points de terminaison et l'authentification coexistent, et où chaque commande renvoie un JSON prêt pour un agent. L'exportation fait le pont entre les deux, vous n'êtes donc jamais bloqué.
Choisissez l'approche qui correspond à votre équipe. Si vous vivez déjà dans Git avec une pile d'outils à usage unique, gardez-les et ajoutez `apidog export` lorsque vous souhaitez un artefact portable. Si vous préférez ne pas maintenir l'assemblage, téléchargez Apidog, installez l'interface de ligne de commande et concevez votre prochaine API sans toucher une souris.