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 x- le 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 comportement de votre API sur votre site publié grâce à une gamme d'extensions différentes que vous pouvez ajouter à votre spécification OpenAPI.

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

x-page-title | x-displayName

Changer le nom affiché 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: Users

x-page-description

Ajouter une description à la page.

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."

x-page-icon

Ajouter 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: "Users"
    x-page-description: "Manage user accounts and profiles."
    x-page-icon: "user"

parent | x-parent

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

parent est le nom de propriété officiel dans OpenAPI 3.2+. Si vous utilisez des versions d'OpenAPI antérieures à la 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: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

x-enable-proxy

Acheminer les requêtes « Test it » via le proxy OpenAPI de GitBook.

Ajoutez-le à la racine pour l'appliquer à toutes les opérations. Ajoutez-le sur une opération pour l'appliquer à ce point de terminaison. Les opérations remplacent la valeur racine.

openapi.yaml

openapi: '3.0.3'
info: ...

# Enable proxy for all operations
x-enable-proxy: true

paths:
  /health:
    get:
      summary: Health check
      # Opt out for a single operation
      x-enable-proxy: false
      responses:
        '200':
          description: OK

En savoir plus dans Utilisation du proxy OpenAPI.

x-codeSamples

Afficher, masquer ou inclure des exemples de code personnalisés pour un bloc OpenAPI.

Champs

Nom du champ	Type	Description
lang	string	Langage de l'exemple de code. La valeur doit être l'une des suivantes liste
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

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example 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

Ajouter une description individuelle pour chacun 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é rejeté.

x-internal | x-gitbook-ignore

Masquer un endpoint de votre référence d'API.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

x-stability

Marquer les endpoints instables ou en cours de développement.

Valeurs prises en charge : experimental, alpha, beta.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      x-stability: experimental

deprecated

Indiquer si un endpoint est obsolète ou non. Les endpoints obsolètes généreront des avertissements de dépréciation sur votre site publié.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true

x-deprecated-sunset

Ajouter une date de retrait pour une opération dépréciée.

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

openapi.yaml

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