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 avez une spécification OpenAPI, vous pouvez l’ajouter à votre organisation en téléversant directement le fichier, en liant une URL hébergée, ou en utilisant le GitBook CLI.

GitBook accepte Swagger 2.0, OpenAPI 3.0, et OpenAPI 3.1 les spécifications pour les téléversements de fichiers, les URL hébergées et la publication via CLI. Pour le résumé de compatibilité actuel, consultez la compatibilité OpenAPI.

Comment ajouter une spécification

1. Ouvrez la section OpenAPI 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éversez un fichier (par ex. openapi.yaml)
   • Saisissez l’URL d’une spécification hébergée
   • Utilisez la 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 de la CLI, quel que soit le mode d’ajout initial.

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 Vérifier les 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.

Avec la 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 aussi utiliser la CLI pour Vérifier les mises à jour en exécutant la commande de publication sur la même URL.

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