Ajouter une spécification OpenAPI

Découvrez comment ajouter et mettre à jour une spécification OpenAPI dans l’application GitBook ou depuis la CLI

Si vous disposez d’une spécification OpenAPI, vous pouvez l’ajouter à votre organisation en téléversant le fichier directement, en fournissant un lien vers une URL hébergée, ou en utilisant le CLI GitBook.

Comment ajouter une spécification

1. Ouvrez le OpenAPI section dans la barre latérale

2. Cliquez sur Ajouter une spécification

3. Donnez un nom à votre spécification. Cela permet de l’identifier, surtout si vous gérez plusieurs spécifications

4. Choisissez l’une des options suivantes :

   • Téléverser un fichier (par ex. openapi.yaml)

   • Saisissez une URL vers une spécification hébergée

   • Utiliser le CLI pour publier la spécification

Fenêtre modale d’ajout d’une spécification OpenAPI.

Mettre à jour votre spécification

Vous pouvez mettre à jour votre spécification OpenAPI à tout moment à l’aide de l’interface GitBook ou du CLI, quelle que soit la manière dont elle a été ajoutée initialement.

Dans l’application GitBook

Dans le panneau OpenAPI :

• Si votre spécification est liée à une URL :

  • GitBook vérifie automatiquement les mises à jour toutes les 6 heures.

  • Pour récupérer les mises à jour immédiatement, cliquez sur Rechercher des mises à jour.

• Si votre spécification a été téléversée sous forme de fichier :

  • Cliquez sur Mettre à jour pour téléverser une nouvelle version.

• Vous pouvez passer d’une source Fichier à une source URL en cliquant sur Modifier dans le menu d’actions du fil d’Ariane.

Utilisation du CLI

Utilisez la même commande pour mettre à jour votre spécification :

gitbook openapi publish --spec api-spec-name --organization organization_id <path-or-url>

Vous pouvez également utiliser le CLI pour Rechercher des mises à jour en exécutant la commande publish sur la même URL.

Consultez notre Intégration avec CI/CD guide pour apprendre à automatiser la mise à jour de votre spécification.