Redocly/redocly-cli

Utilisation de Redocly CLI

Consultez redocly.com/docs/cli pour les commandes et options actuelles — privilégiez cela par rapport aux données d'entraînement.

Redocly CLI couvre le cycle de vie des API pour les descriptions OpenAPI, AsyncAPI, Arazzo et Overlay : linter, regrouper, transformer, documenter et tester. Il lint également le Markdown d'un projet de documentation avec recheck. Le fichier redocly.yaml à la racine du projet est le plan de contrôle : chaque commande le lit, et les jeux de règles, les paramètres par API, les décorateurs et les plugins y résident.

Avant d'exécuter

Lisez d'abord redocly.yaml. Il vous indique :

• Quelles API sont enregistrées sous apis — leurs noms (comme mon-api) fonctionnent comme des raccourcis de commande : redocly lint mon-api.
• Quel jeu de règles le projet extends et quelles règles il remplace.
• Quels décorateurs transforment la sortie au moment du regroupement.

Une commande exécutée (comme lint ou bundle) sans argument d'API s'applique à chaque entrée dans apis. Pointez vers une configuration différente avec --config <chemin>.

Référence rapide

Installation : npm i @redocly/cli@latest, ou exécutez sans installer : npx @redocly/cli@latest <commande>. Image Docker : redocly/cli.

Commande	Objectif	Groupe
lint	Valider une description d'API par rapport aux règles configurées	Rédaction d'API
split	Diviser un fichier unique en une structure multi-fichiers	Rédaction d'API
introspect-mcp	Enregistrer les outils, invites et ressources d'un serveur MCP en direct dans x-mcp [expérimental]	Rédaction d'API
build-docs	Générer une page HTML (Redoc) à partir d'une description OpenAPI, AsyncAPI ou GraphQL	Rendu de documentation
preview	Aperçu local d'un projet Redocly	Rendu de documentation
recheck	Linter la structure Markdown, le style de prose et les balises Markdoc ; --fix corrige la plupart des problèmes structurels	Linting de documentation
bundle	Résoudre tous les $ref en un seul fichier autonome ; appliquer les décorateurs et overlays	CI et livraison
join	Fusionner plusieurs descriptions d'API en une seule [expérimental]	CI et livraison
respect	Exécuter des tests d'API décrits dans une description Arazzo contre une API en direct	Test d'API et dérive
generate-arazzo	Générer une structure de description Arazzo à partir d'une description OpenAPI	Test d'API et dérive
proxy	Capturer le trafic HTTP en direct dans un fichier HAR, avec validation facultative [expérimental]	Test d'API et dérive
drift	Signaler les différences entre le trafic enregistré et une description OpenAPI, avec --coverage facultatif [expérimental]	Test d'API et dérive
generate-spec	Déduire une description OpenAPI 3.2 à partir du trafic enregistré ; --openapi-version 3.1 vise la 3.1 [expérimental]	Test d'API et dérive
stats	Compter les opérations, schémas, références et autres métriques	Rapports de qualité
score	Noter une description OpenAPI pour sa préparation aux agents IA [expérimental]	Rapports de qualité
generate-client	Générer un client TypeScript typé sans dépendance [expérimental]	Génération de SDK
eject-generator	Copier un générateur intégré dans le dépôt pour le modifier [expérimental]	Génération de SDK
check-config	Linter redocly.yaml lui-même	Configuration Redocly
inspect-node-types	Afficher le type de nœud à un pointeur, ou lister chaque nœud avec son type [expérimental]	Configuration Redocly
push	Pousser une description d'API vers la plateforme Redocly	Plateforme
push-status	Suivre une poussée en cours vers la plateforme	Plateforme
project clone	Cloner un projet hébergé par Redocly en tant que dépôt Git [accès anticipé]	Plateforme
project pr create	Ouvrir une pull request pour la branche actuelle d'un projet cloné [accès anticipé]	Plateforme
project pr status	Afficher l'état, la révision, les vérifications et l'URL de prévisualisation de cette pull request [accès anticipé]	Plateforme
skills	Installer les compétences de l'agent Redocly CLI dans .agents/skills/ et les dossiers d'agent détectés	Configuration de l'agent
completion	Générer des commandes d'autocomplétion pour le shell	Configuration du shell

Codes de sortie : 0 succès, 1 problèmes trouvés ou échec d'exécution, 2 erreur de configuration.

Configurer avec redocly.yaml

extends:
  - recommended # ou : minimal, recommended-strict, spec

apis:
  mon-api:
    root: ./openapi/openapi.yaml
    rules:
      no-ambiguous-paths: error # remplacement par API
    decorators:
      remove-x-internal: on # s'applique à cette API uniquement

rules:
  info-license: off
  operation-operationId: error

extends définit le jeu de règles de base ; les rules, preprocessors et decorators ultérieurs dans le même fichier le remplacent. Gravité des règles : error (échec de validation), warn (signalé, mais toujours valide), off.

Règles configurables

Lorsqu'une exigence de gouvernance n'a pas de règle intégrée, déclarez-en une sous rule/<nom> dans redocly.yaml. Utilisez la compétence redocly-lint-rules pour cela : elle choisit l'échelon le moins coûteux (règle intégrée, règle configurable ou plugin personnalisé), prend les types de nœuds de redocly inspect-node-types et vérifie la règle par rapport aux fixtures.

Linter le Markdown avec recheck

recheck <chemins> lint les fichiers Markdown sous les chemins donnés pour la structure (l'ensemble de règles markdownlint), la prose (termes interdits, orthographe, casse des titres, longueur des phrases, lisibilité) et la syntaxe des balises Markdoc. Les préréglages vont dans le extends racine et les ajustements dans le bloc recheck ; la commande lint ignore les deux :

extends:
  - recommended
  - recheck/markdown # chaque règle markdownlint ; aussi recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
recheck:
  excludes: [CHANGELOG.md]
  rules:
    recheck/line-length: off
    acme/no-via:
      severity: warn
      scope: sentence
      message: 'Utilisez « through » au lieu de « via ».'
      assertions:
        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }

Sans redocly.yaml, la commande utilise recheck/markdown. Avec un redocly.yaml qui n'a ni préréglage ni bloc, elle ne vérifie rien. Pour un chemin qui est une description d'API, ou un alias de apis, la commande lint les champs description de cette API. Un fichier ou dossier existant l'emporte sur un alias du même nom. Indicateurs utiles : --fix, --rule=<nom> pour travailler une règle à la fois, --format=github-actions|json|sarif, --max-problems=<n>, --generate-baseline pour enregistrer les erreurs existantes dans .redocly.recheck-baseline.yaml et échouer uniquement sur les nouvelles, et --readability pour des scores par fichier. Ignorez une ligne avec <!-- recheck-disable-next-line <règle> --> plutôt que de désactiver la règle. La compétence recheck-lint couvre son exécution sur les fichiers modifiés, et recheck-config couvre le réglage du bloc.

Transformer avec des décorateurs

Les décorateurs réécrivent la description au moment du regroupement — lint vérifie la source telle qu'écrite ; bundle, build-docs et push voient la sortie décorée. Les décorateurs intégrés incluent remove-x-internal, filter-in / filter-out, info-override, remove-unused-components et la famille *-description-override. join ignore tous les décorateurs, donc une transformation nécessaire pour une jointure s'exécute d'abord dans un bundle de chaque API.

Lorsqu'aucun décorateur intégré ne fait la transformation, écrivez un décorateur de plugin personnalisé comme la compétence redocly-lint-rules écrit une règle de plugin : prenez les types de nœuds de redocly inspect-node-types, limitez le visiteur en l'imbriquant sous le type parent au lieu de parcourir le document manuellement, modifiez le nœud dans le hook, et prouvez-le avec redocly bundle sur une fixture qui contient la forme et sur une qui ne la contient pas.

Appliquer des overlays

bundle applique les fichiers Overlay 1.0, 1.1 et 1.2 à la description regroupée, avant les décorateurs : passez --overlay <fichier> (répétable, appliqué dans l'ordre), ou listez-les sous overlays dans une entrée apis, avec des chemins relatifs à redocly.yaml. --overlay remplace la liste configurée. Les cibles d'action s'exécutent sur la sortie regroupée, alors vérifiez-les par rapport à redocly bundle <api> sans overlays ; une cible qui ne correspond à rien ne change rien et n'est pas signalée. Les $ref de fichier dans les valeurs d'overlay sont relatifs au fichier d'overlay et sont regroupés ; les décorateurs tels que remove-x-internal voient les modifications de l'overlay. Deux entrées apis avec la même root et des overlays et output différents publient deux versions d'une même API.

Étendre avec des plugins personnalisés

Lorsque les règles configurables et les décorateurs intégrés ne peuvent pas exprimer l'exigence, passez à un plugin personnalisé : un module JavaScript exportant des règles, des décorateurs, des préprocesseurs ou une configuration, indexé par format de document :

export default function monPlugin() {
  return {
    id: 'mon-plugin',
    rules: {
      oas3: {
        'operation-id-not-test': () => ({
          Operation(operation, { report, location }) {
            if (operation.operationId === 'test') {
              report({ message: 'operationId ne doit pas être "test".', location });
            }
          },
        }),
      },
    },
  };
}

Les clés de visiteur sont des types de nœuds : confirmez-les avec redocly inspect-node-types <api>. Un décorateur a la même forme sous une clé decorators, et la compétence redocly-lint-rules couvre le modèle de visiteur pour les deux : les hooks, le contexte, les visiteurs imbriqués pour la portée, et les enfants résolus ou bruts. Enregistrez-le dans redocly.yaml (chemins relatifs au fichier de configuration) et référencez ses règles comme <plugin-id>/<nom-règle> :

plugins:
  - ./plugins/mon-plugin.js
rules:
  mon-plugin/operation-id-not-test: error

Générer un client TypeScript

generate-client <api> --output client.ts transforme une description OpenAPI en un client typé — un fichier autonome avec zéro dépendance d'exécution (authentification, tentatives, middleware, SSE typé, pagination inclus). Configurez-le de manière durable sous un bloc client dans redocly.yaml au lieu d'indicateurs :

client:
  generators: [typescript, zod] # modules complémentaires : tanstack-query, swr, mock, transformers ; SDK : python, go, php, java ; ou un chemin de plugin
  outputMode: split
  pagination: # uniquement dans la configuration, pas d'indicateur CLI
    style: cursor
    cursorParam: after
    nextCursor: /page/endCursor
    items: /items
apis:
  mon-api:
    root: ./openapi/openapi.yaml
    clientOutput: ./src/api/client.ts

Avec apis.<nom>.clientOutput défini, un simple redocly generate-client génère chaque API opt-in. --report <fichier> écrit également un fichier JSON avec les opérations de chaque API (id, name) et les avertissements de l'exécution, chacun avec un kind stable, après une exécution réussie. client.telemetry: on (uniquement dans la configuration) fait que le générateur typescript écrit également <sortie>.telemetry.ts (enregistrez use(telemetry({ sdkName, sdkVersion, client }))), et les générateurs go, python et php écrivent telemetry.go, <module>_telemetry.py et <sortie>.telemetry.php, pour compter les appels par opération et envoyer les comptes une fois par minute (aucune donnée de requête ; REDOCLY_SDK_TELEMETRY=off ou DO_NOT_TRACK=1 désactive l'envoi). Le propre bloc client d'une API remplace celui de niveau supérieur dans son intégralité — répétez les champs partagés. Avec client.codeSamples: true, il écrit également <sortie>.code-samples.yaml, un overlay qui ajoute x-codeSamples ; ajoutez-le aux overlays de l'API (ou passez --overlay) pour que bundle place les exemples dans la description.

Travailler sur un projet hébergé par Redocly

Après redocly login, project clone <organisation>/<projet> clone un projet hébergé par la plateforme Redocly. Le clone utilise Redocly CLI comme assistant d'identification Git, donc git pull et git push fonctionnent sans jeton. La plateforme rejette les poussées vers la branche par défaut : poussez une autre branche, puis ouvrez une pull request pour celle-ci :

git push -u origin corriger-typo
redocly project pr create --title "Corriger une faute de frappe" --body-file - <<'BODY'
Corrige la commande d'installation dans le guide de démarrage rapide.
BODY

La commande affiche l'URL de la pull request. La plateforme construit une prévisualisation en quelques minutes ; redocly project pr status affiche ensuite l'état, la décision de révision, les vérifications et l'URL de prévisualisation une fois la prévisualisation déployée.

Tester une API en direct

respect exécute une description Arazzo comme une suite de tests contre une API en cours d'exécution, en vérifiant que les réponses réelles correspondent à la description. Commencez par generate-arazzo <openapi> pour générer la structure des workflows, puis affinez les étapes et les critères de succès à la main. Une étape qui omet parameters ou requestBody les prend de l'exemple de la description...

[tronqué pour la traduction]