Référence des extensions

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

Vous pouvez améliorer votre spécification OpenAPI en utilisant des 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 pour répondre à différents besoins.

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

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

x-page-title | x-displayName

Modifiez le nom affiché d'une étiquette utilisée 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 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 profils des utilisateurs."
    x-page-icon: "user"

x-parent | parent

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

openapi.yaml

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

x-hideTryItPanel

Affichez ou masquez le bouton « Tester » pour un bloc OpenAPI.

openapi.yaml

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

x-codeSamples

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

Fields

Field Name	Type	Description
lang	string	Langage de l'exemple de code. La valeur doit être l'une des suivantes list
label	string	Étiquette de l'exemple de code, par exemple Node ou Python2.7, optionnel, lang est utilisé par défaut
source	string	Code source de l'exemple de code

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Description d'exemple
      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 chacun des enum valeurs dans 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é rejeté.

x-internal | x-gitbook-ignore

Cachez un point de terminaison de votre référence API.

openapi.yaml

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

x-stability

Marquez les points de terminaison qui sont 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: Description d'exemple
      operationId: examplePath
      x-stability: expérimental

déprécié

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

openapi.yaml

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

x-deprecated-sunset

Ajoutez une date de fin de support à 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: Description d'exemple
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05