Référence des extensions

La référence complète des extensions OpenAPI prises en charge par GitBook

Vous pouvez enrichir votre spécification OpenAPI à l’aide d’extensions — des champs personnalisés qui commencent par le x- préfixe. Ces extensions vous permettent d’ajouter des informations supplémentaires et d’adapter la documentation de votre API à différents besoins.

GitBook vous permet d’ajuster l’apparence et le fonctionnement de votre API sur votre site publié grâce à une gamme de différentes extensions que vous pouvez ajouter à votre spécification OpenAPI.

Rendez-vous dans notre section des guides pour en savoir plus sur l’utilisation des extensions OpenAPI pour configurer votre documentation.

x-page-title | x-displayName

Modifiez le nom d’affichage d’un tag utilisé dans la navigation et le titre de la page.

openapi.yaml

openapi: '3.0'
info: ...
tags :
  - name: users
    x-page-title: Utilisateurs

x-page-description

Ajoutez une description à la page.

openapi.yaml

openapi: '3.0'
info: ...
tags :
  - name: "users"
    x-page-title: "Utilisateurs"
    x-page-description: "Gérez les comptes et les profils des utilisateurs."

x-page-icon

Ajoutez une icône Font Awesome à la page. Voir les icônes disponibles ici.

openapi.yaml

openapi: '3.0'
info: ...
tags :
  - name: "users"
    x-page-title: "Utilisateurs"
    x-page-description: "Gérez les comptes et les profils des utilisateurs."
    x-page-icon: "user"

parent | x-parent

Ajoutez une hiérarchie aux tags pour organiser vos pages dans GitBook.

parent est le nom officiel de la propriété dans OpenAPI 3.2+. Si vous utilisez des versions d’OpenAPI antérieures à 3.2 (3.0.x, 3.1.x), utilisez x-parent à la place.

openapi.yaml

openapi: '3.2'
info: ...
tags :
  - name: organization
  - name: admin
    parent: organization
  - name: user
    parent: organization    

x-hideTryItPanel

Afficher ou masquer le bouton « Test it » pour un bloc OpenAPI.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

x-expandAllResponses

Développez toutes les sections de réponse par défaut, au lieu d’en afficher une seule à la fois.

Ajoutez-le à la racine pour l’appliquer à chaque opération. Ajoutez-le sur une opération pour l’appliquer à ce seul point de terminaison.

openapi.yaml

openapi: '3.0'
info: ...

# Développer toutes les réponses pour chaque opération
x-expandAllResponses: true

paths:
  /pets:
    get:
      summary: Lister les animaux de compagnie
      responses: [...]
      # Désactiver pour une seule opération
      x-expandAllResponses: false

x-expandAllModelSections

Développez par défaut toutes les sections des modèles/schémas, en affichant les propriétés d’objets imbriqués sans nécessiter d’action de l’utilisateur.

Ajoutez-le à la racine pour l’appliquer à chaque opération. Ajoutez-le sur une opération pour l’appliquer à ce seul point de terminaison.

openapi.yaml

openapi: '3.0'
info: ...

# Développer toutes les sections de modèle pour chaque opération
x-expandAllModelSections: true

paths:
  /pets:
    post:
      summary: Créer un animal de compagnie
      requestBody: [...]
      responses: [...]
      # Désactiver pour une seule opération
      x-expandAllModelSections: false

x-enable-proxy

Faites passer les requêtes « Test it » par le proxy OpenAPI de GitBook.

Ajoutez-le à la racine pour l’appliquer à chaque opération. Ajoutez-le sur une opération pour l’appliquer à ce seul point de terminaison. Les opérations remplacent la valeur de la racine.

openapi.yaml

openapi: '3.0.3'
info: ...

# Activer le proxy pour toutes les opérations
x-enable-proxy: true

paths:
  /health:
    get:
      summary: Vérification de l’état
      # Désactiver pour une seule opération
      x-enable-proxy: false
      responses:
        '200':
          description: OK

En savoir plus dans Utilisation du proxy OpenAPI.

x-codeSamples

Affichez, masquez ou incluez des exemples de code personnalisés pour un bloc OpenAPI.

Champs

Nom du champ	Tapez	Description
lang	string	Langue de l’exemple de code. La valeur doit être l’une des suivantes liste
libellé	string	Libellé de l’exemple de code, par exemple Node ou Python2.7, facultatif, lang est utilisé par défaut
source	string	Code source de l’exemple

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl -L \\
            -H 'Authorization: Bearer <token>' \\
            'https://api.gitbook.com/v1/user'

x-enumDescriptions

Ajoutez une description individuelle pour chacune des enum valeurs de votre schéma.

openapi.yaml

openapi: '3.0'
info: ...
components:
  schemas:
    project_status:
      type: string
      enum:
        - LIVE
        - PENDING
        - REJECTED
      x-enumDescriptions:
        LIVE: Le projet est en ligne.
        PENDING: Le projet est en attente d’approbation.
        REJECTED: Le projet a été refusé.

x-internal | x-gitbook-ignore

Masquez un point de terminaison de votre référence d’API.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

x-stability

Marquez les points de terminaison instables ou en cours de développement.

Valeurs prises en charge : expérimental, alpha, bêta.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      x-stability: experimental

obsolète

Indiquez si un point de terminaison est obsolète ou non. Les points de terminaison obsolètes afficheront des avertissements de dépréciation dans votre site publié.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true

x-deprecated-sunset

Ajoutez une date de fin de vie à une opération obsolète.

Valeurs prises en charge : ISO 8601 format (YYYY-MM-DD)

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05