Blog

Tutoriel Redocly : Comment utiliser l'interface en ligne de commande (CLI) Redocly

Mark Ponomarev

Mark Ponomarev

9 June 2025

Tutoriel Redocly : Comment utiliser l'interface en ligne de commande (CLI) Redocly

Bienvenue dans ce tutoriel complet sur Redocly CLI ! Redocly CLI est un outil puissant et tout-en-un en ligne de commande pour les définitions OpenAPI et Swagger. Il vous aide à construire, gérer et vérifier la qualité de vos descriptions d'API tout au long du cycle de vie de l'API. Que vous soyez développeur, rédacteur technique ou chef de produit API, cet outil a quelque chose pour vous.

Ce tutoriel vise à être une exploration approfondie de Redocly CLI, vous faisant passer de débutant à utilisateur confiant. Nous couvrirons tout, de l'installation aux fonctionnalités avancées comme les règles de linting personnalisées et l'intégration CI/CD. À la fin de ce tutoriel, vous serez capable d'intégrer Redocly CLI dans votre flux de travail quotidien pour améliorer la qualité et la documentation de votre API.

💡
Vous cherchez un excellent outil de test d'API qui génère une magnifique documentation d'API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et remplace Postman à un prix beaucoup plus abordable !
button

Qu'est-ce que Redocly CLI ?

Comme indiqué dans sa documentation officielle, Redocly CLI est votre "utilitaire OpenAPI tout-en-un". Il prend en charge OpenAPI 3.1, 3.0, 2.0 (ancien Swagger), AsyncAPI, et plus encore. Il est conçu pour vous aider avec :

Cet outil est conçu en tenant compte des performances et de l'expérience utilisateur, offrant une exécution rapide et des messages d'erreur lisibles par l'homme.

Pourquoi utiliser Redocly CLI ?

Dans le monde actuel où l'API est primordiale, maintenir des définitions d'API de haute qualité est crucial. Redocly CLI vous aide à y parvenir en :

Ce que ce tutoriel couvrira

Ce tutoriel est structuré pour fournir un guide étape par étape pour maîtriser Redocly CLI. Voici ce que nous couvrirons :

Commençons !

Chapitre 1 : Premiers pas avec Redocly CLI

Ce chapitre vous guidera à travers les premières étapes de l'utilisation de Redocly CLI, de l'installation à l'exécution de votre première commande.

Prérequis

Avant de commencer, assurez-vous d'avoir les éléments suivants installés sur votre système :

Installation

Vous avez plusieurs options pour installer et utiliser Redocly CLI. Choisissez celle qui correspond le mieux à vos besoins.

Utilisation de npx (Recommandé pour une utilisation rapide)

Si vous souhaitez simplement essayer Redocly CLI sans installation globale, vous pouvez utiliser npx, l'exécuteur de paquets npm. Cette commande téléchargera et exécutera la dernière version de Redocly CLI.

npx @redocly/cli@latest --version

Pour utiliser n'importe quelle commande redocly, il suffit de préfixer npx @redocly/cli@latest. Par exemple :

npx @redocly/cli@latest lint openapi.yaml

C'est un excellent moyen d'utiliser Redocly CLI dans des environnements CI/CD ou si vous ne souhaitez pas encombrer votre système avec des paquets globaux.

Installation globale avec npm

Pour une utilisation régulière, une installation globale est plus pratique. Elle rend la commande redocly directement disponible dans votre terminal.

npm install -g @redocly/cli@latest

Après l'installation, vous pouvez la vérifier en vérifiant la version :

redocly --version

Vous pouvez maintenant exécuter des commandes comme celle-ci :

redocly lint openapi.yaml

Utilisation de Docker

Si vous préférez utiliser Docker, Redocly fournit une image Docker pré-construite. C'est utile pour isoler l'outil de votre environnement local.

Tout d'abord, téléchargez l'image depuis Docker Hub :

docker pull redocly/cli

Pour exécuter une commande, vous devez monter votre répertoire de travail actuel (où se trouvent vos fichiers API) en tant que volume dans le conteneur Docker.

docker run --rm -v $PWD:/spec redocly/cli lint /spec/openapi.yaml

Dans cette commande, $PWD fait référence à votre répertoire actuel, qui est monté sur le répertoire /spec à l'intérieur du conteneur. Vous devez ensuite faire référence à vos fichiers en utilisant le chemin /spec.

Structure de base des commandes

La structure de base pour utiliser Redocly CLI est la suivante :

redocly [commande] [arguments] [options]

Vous pouvez toujours obtenir de l'aide pour une commande spécifique en utilisant l'option --help :

redocly lint --help

Maintenant que vous avez installé Redocly CLI et que vous comprenez la structure de base des commandes, passons à l'exploration de ses fonctionnalités puissantes.

Chapitre 2 : Commandes et fonctionnalités principales

Ce chapitre couvre les commandes principales de Redocly CLI. Nous explorerons comment linter, gérer, documenter et analyser vos définitions d'API. Pour les exemples de ce chapitre, nous utiliserons un simple fichier openapi.yaml.

Créons un fichier nommé openapi.yaml avec le contenu suivant :

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Section 2.1 : Linting de vos descriptions d'API (lint)

Le linting d'API est le processus de vérification de votre fichier de définition d'API pour la cohérence, la correction et le style. Il vous aide à appliquer les directives de conception d'API et à détecter les problèmes potentiels avant qu'ils n'atteignent la production.

Utilisation de base

La commande lint est utilisée pour vérifier votre définition d'API par rapport à un ensemble de règles.

redocly lint openapi.yaml

Par défaut, redocly lint utilise l'ensemble de règles recommended. Si notre openapi.yaml présente des problèmes, la sortie les détaillera. Pour notre fichier d'exemple, la sortie devrait être :

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Configuration des règles

Redocly CLI est livré avec trois ensembles de règles configurables intégrés :

Vous pouvez spécifier un ensemble de règles avec l'option --extends :

redocly lint openapi.yaml --extends=minimal

Vous pouvez également créer vos propres ensembles de règles personnalisés dans un fichier de configuration redocly.yaml. Nous couvrirons cela au Chapitre 3.

Formats de sortie

La commande lint prend en charge divers formats de sortie en utilisant l'option --format, ce qui est très utile pour l'intégration avec d'autres outils.

Exemple d'utilisation du format stylish :

redocly lint openapi.yaml --format=stylish

Ignorer les problèmes

Parfois, vous pourriez avoir besoin d'ignorer un problème spécifique. Vous pouvez générer un fichier .redocly.lint-ignore.yaml pour supprimer les erreurs et les avertissements.

redocly lint openapi.yaml --generate-ignore-file

Cette commande créera un fichier d'ignorance. Si vous exécutez à nouveau lint, les problèmes listés dans ce fichier seront ignorés. Cela vous donne un contrôle granulaire sur le processus de linting.

Section 2.2 : Gestion des descriptions d'API avec bundle et split

Au fur et à mesure que votre API se développe, la gestion d'un seul fichier OpenAPI monolithique devient fastidieuse. Redocly CLI propose deux commandes pour vous aider : split et bundle.

Division d'un grand fichier OpenAPI (split)

La commande split vous permet de décomposer un grand fichier de définition d'API en une structure multi-fichiers plus gérable. Elle extrait les composants, les chemins et les exemples dans des fichiers et dossiers séparés.

Divisons notre openapi.yaml :

redocly split openapi.yaml --outDir=split-api

Cette commande créera un répertoire split-api avec la structure suivante :

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

Le nouveau fichier openapi.yaml dans split-api utilisera maintenant $ref pour lier aux fichiers externes :

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

Cela rend la gestion des différentes parties de votre API beaucoup plus facile.

Regroupement de plusieurs fichiers (bundle)

La commande bundle fait l'inverse de split. Elle prend un fichier de définition d'API racine et résout toutes les références $ref locales pour créer un seul fichier autonome. C'est utile pour les outils qui ne prennent pas en charge les définitions multi-fichiers.

Regroupons notre API divisée en un seul fichier :

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

Le fichier bundled-api.yaml aura le même contenu que notre fichier openapi.yaml original.

Déréférencement

La commande bundle peut également créer un fichier entièrement déréférencé, où toutes les références $ref (y compris les références distantes) sont résolues et remplacées par leur contenu.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

Cela peut être utile, mais sachez que cela peut rendre le fichier beaucoup plus grand et que les références circulaires peuvent causer des problèmes avec la sortie JSON.

Section 2.3 : Génération de documentation d'API (build-docs)

L'une des fonctionnalités les plus puissantes de Redocly CLI est sa capacité à générer une documentation de référence d'API magnifique et interactive en utilisant le moteur open source Redoc.

Utilisation de base

Pour générer de la documentation, utilisez la commande build-docs :

redocly build-docs openapi.yaml

Cela créera un fichier redoc-static.html dans votre répertoire actuel. Ouvrez-le dans votre navigateur pour voir votre documentation.

Vous pouvez spécifier un autre fichier de sortie avec l'option -o ou --output :

redocly build-docs openapi.yaml -o my-api-docs.html

Personnalisation de la sortie

Vous pouvez personnaliser l'apparence de votre documentation en utilisant l'option --theme.openapi. Cela vous permet de modifier les couleurs, les polices et même de désactiver des parties de l'interface utilisateur comme la barre de recherche.

Par exemple, pour désactiver la barre de recherche :

redocly build-docs openapi.yaml --theme.openapi.disableSearch

Vous pouvez trouver toutes les options de thème disponibles dans la documentation officielle de Redocly.

Pour encore plus de contrôle, vous pouvez fournir votre propre modèle Handlebars pour rendre la documentation. C'est une fonctionnalité avancée qui permet une personnalisation complète de la sortie HTML.

Section 2.4 : Obtention de statistiques d'API (stats)

La commande stats fournit des métriques utiles sur votre définition d'API, telles que le nombre de chemins, d'opérations, de schémas, et plus encore.

Comment obtenir des statistiques

Pour obtenir des statistiques pour votre API, exécutez simplement :

redocly stats openapi.yaml

La sortie par défaut est au format stylish :

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Différents formats

Comme la commande lint, stats prend en charge différents formats de sortie avec l'option --format. Les formats json et markdown sont particulièrement utiles.

redocly stats openapi.yaml --format=json

C'est excellent pour alimenter les statistiques dans d'autres outils ou tableaux de bord.

redocly stats openapi.yaml --format=markdown

Cela génère une table Markdown, parfaite pour les rapports ou pour une utilisation dans les résumés GitHub Actions, comme nous le verrons dans le chapitre suivant.

Chapitre 3 : Sujets avancés

Dans ce chapitre, nous allons explorer certaines des fonctionnalités plus avancées de Redocly CLI, y compris le puissant fichier de configuration et l'intégration avec les pipelines CI/CD.

Fichier de configuration (redocly.yaml)

Bien que vous puissiez utiliser Redocly CLI entièrement depuis la ligne de commande, un fichier de configuration redocly.yaml vous permet de stocker votre configuration en un seul endroit, rendant vos commandes plus courtes et votre configuration réutilisable.

Créons un fichier redocly.yaml à la racine de notre projet :

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Structure du fichier de configuration

Utilisation des alias d'API

Avec la section apis configurée, vous pouvez maintenant utiliser l'alias main au lieu du chemin du fichier dans vos commandes :

redocly lint main
redocly stats main
redocly build-docs main

C'est particulièrement utile lorsque vous avez plusieurs API dans votre projet. Si vous exécutez redocly lint sans aucun argument, il linera toutes les API définies dans la section apis.

Intégration Continue (CI)

L'intégration de Redocly CLI dans votre pipeline CI/CD est un excellent moyen d'automatiser les contrôles de qualité de l'API. Voici un exemple de comment l'utiliser avec GitHub Actions.

Créez un fichier nommé .github/workflows/redocly.yaml :

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

Ce flux de travail GitHub Actions effectue les opérations suivantes :

  1. Il se déclenche à chaque push et pull request vers la branche main.
  2. Il récupère votre code.
  3. Il installe Node.js et Redocly CLI.
  4. Il exécute la commande lint avec le format github-actions. Cela annotera automatiquement tous les problèmes directement dans vos pull requests.
  5. Il exécute la commande stats avec le format markdown et ajoute la sortie au résumé du job, vous donnant un beau rapport à chaque exécution.

C'est un moyen puissant de garantir que vos définitions d'API sont toujours en bon état.

Chapitre 4 : Exemple pratique : Un flux de travail complet

Dans ce dernier chapitre, nous allons rassembler tout ce que nous avons appris et parcourir un flux de travail complet et pratique. Nous allons :

  1. Créer une structure de projet avec une définition d'API multi-fichiers.
  2. Créer un fichier de configuration redocly.yaml.
  3. Linter la définition d'API en utilisant notre configuration personnalisée.
  4. Regrouper l'API en un seul fichier.
  5. Générer de la documentation d'API.

1. Configuration du projet

Créons un nouveau répertoire pour notre projet et configurons la structure des fichiers.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Maintenant, créons les fichiers API divisés.

openapi/components/schemas/Pet.yaml :

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml :

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (notre point d'entrée principal) :

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. Créer redocly.yaml

Maintenant, créons notre fichier de configuration à la racine du répertoire redocly-petstore.

redocly.yaml :

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

Dans cette configuration, nous avons défini un alias petstore@v1 pour notre API et ajouté quelques règles de linting personnalisées.

3. Linter l'API

Maintenant, linterons notre API en utilisant notre nouvelle configuration.

redocly lint petstore@v1

Vous verrez des erreurs et des avertissements car notre API ne se conforme pas encore à toutes nos nouvelles règles. Par exemple, nous n'avons pas de tags avec des descriptions. Cela démontre comment vous pouvez appliquer votre propre guide de style d'API.

4. Regrouper l'API

Ensuite, regroupons notre API multi-fichiers en un seul fichier distribuable.

redocly bundle petstore@v1 -o dist/petstore.yaml

Cela créera un répertoire dist avec un fichier petstore.yaml à l'intérieur, contenant la définition d'API entièrement résolue.

5. Générer de la documentation

Enfin, générons notre documentation d'API.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

Cela créera dist/petstore-docs.html. Ouvrez ce fichier dans votre navigateur pour voir votre magnifique documentation d'API interactive.

Et voilà ! Un flux de travail complet, d'une définition d'API structurée et multi-fichiers à un fichier regroupé et une documentation professionnelle, le tout géré avec Redocly CLI.

Conclusion

Dans ce tutoriel, nous avons exploré en profondeur Redocly CLI. Nous avons commencé par les bases de l'installation et des commandes principales, puis nous sommes passés à des sujets avancés comme la configuration et l'intégration CI, et enfin nous avons parcouru un flux de travail complet et pratique.

Vous devriez maintenant avoir une solide compréhension de la façon d'utiliser Redocly CLI pour :

Redocly CLI est un outil polyvalent et puissant qui peut améliorer considérablement votre flux de travail de développement d'API. Je vous encourage à explorer davantage ses fonctionnalités et à l'intégrer dans vos projets.

Ressources supplémentaires

Merci d'avoir suivi ce tutoriel. Bon développement d'API !

💡
Vous cherchez un excellent outil de test d'API qui génère une magnifique documentation d'API ?

Vous voulez une plateforme intégrée et tout-en-un pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos demandes et replaces Postman at a much more affordable price!
button

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger