# Référence des extensions

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 guides](/docs/documentation/fr/api-references/guides.md) pour en savoir plus sur l’utilisation des extensions OpenAPI pour configurer votre documentation.

<details>

<summary><code>x-page-title | x-displayName</code></summary>

Modifier le nom d’affichage d’une balise utilisée dans la navigation et le titre de la page.

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags:
  - name: users
    x-page-title: Users
```

{% endcode %}

</details>

<details>

<summary><code>x-page-description</code></summary>

Ajouter une description à la page.

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Gérer les comptes et les profils des utilisateurs."
```

{% endcode %}

</details>

<details>

<summary><code>x-page-icon</code></summary>

Ajouter une icône Font Awesome à la page. Voir les icônes disponibles [ici](https://fontawesome.com/search).

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>parent | x-parent</code></summary>

Ajouter une hiérarchie aux balises afin d’organiser vos pages dans GitBook.

{% hint style="warning" %}
`parent` est le nom de propriété officiel 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.
{% endhint %}

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-hideTryItPanel</code></summary>

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

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-expandAllResponses</code></summary>

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

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">openapi: '3.0'
info: ...

# Développer toutes les réponses pour chaque opération
<strong>x-expandAllResponses: true
</strong>
paths :
  /pets:
    get :
      summary: Liste des animaux
      responses: [...]
      # Ne pas l’appliquer à une seule opération
<strong>      x-expandAllResponses: false
</strong></code></pre>

</details>

<details>

<summary><code>x-expandAllModelSections</code></summary>

Développer par défaut toutes les sections de modèle/schéma, en affichant les propriétés d’objets imbriquées sans nécessiter d’interaction de l’utilisateur.

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">openapi: '3.0'
info: ...

# Développer toutes les sections de modèle pour chaque opération
<strong>x-expandAllModelSections: true
</strong>
paths :
  /pets:
    post :
      summary: Créer un animal
      requestBody: [...]
      responses: [...]
      # Ne pas l’appliquer à une seule opération
<strong>      x-expandAllModelSections: false
</strong></code></pre>

</details>

<details>

<summary><code>x-enable-proxy</code></summary>

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

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

{% code title="openapi.yaml" %}

```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
      # Ne pas l’appliquer à une seule opération
      x-enable-proxy: false
      responses :
        '200':
          description: OK
```

{% endcode %}

En savoir plus dans [Utiliser le proxy OpenAPI](/docs/documentation/fr/api-references/guides/using-openapi-proxy.md).

</details>

<details>

<summary><code>x-codeSamples</code></summary>

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

**Champs**

<table><thead><tr><th width="103.625">Nom du champ</th><th width="88.07421875" align="center">Tapez</th><th>Description</th></tr></thead><tbody><tr><td><code>lang</code></td><td align="center">string</td><td>Langue de l’exemple de code. La valeur doit être l’une des suivantes <a href="https://github.com/github/linguist/blob/master/lib/linguist/popular.yml">liste</a></td></tr><tr><td><code>libellé</code></td><td align="center">string</td><td>Libellé de l’exemple de code, par exemple <code>Node</code> ou <code>Python2.7</code>, <em>facultatif</em>, <code>lang</code> est utilisé par défaut</td></tr><tr><td><code>source</code></td><td align="center">string</td><td>Code source de l’exemple de code</td></tr></tbody></table>

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags: [...]
paths :
  /example:
    get :
      summary: Résumé d’exemple
      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'
```

{% endcode %}

</details>

<details>

<summary><code>x-enumDescriptions</code></summary>

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

{% code title="openapi.yaml" %}

```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é.
```

{% endcode %}

</details>

<details>

<summary><code>x-internal | x-gitbook-ignore</code></summary>

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

{% code title="openapi.yaml" %}

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

{% endcode %}

</details>

<details>

<summary><code>x-stability</code></summary>

Marquer les points de terminaison qui sont instables ou en cours de développement.

Valeurs prises en charge : `experimental`, `alpha`, `beta`.

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags: [...]
paths :
  /example:
    get :
      summary: Résumé d’exemple
      description: Description d’exemple
      operationId: examplePath
      x-stability: experimental
```

{% endcode %}

</details>

<details>

<summary><code>deprecated</code></summary>

Marquer 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é.

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags: [...]
paths :
  /example:
    get :
      summary: Résumé d’exemple
      description: Description d’exemple
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
```

{% endcode %}

</details>

<details>

<summary><code>x-deprecated-sunset</code></summary>

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

Valeurs prises en charge : **ISO 8601** format (AAAA-MM-JJ)

{% code title="openapi.yaml" %}

```yaml
openapi: '3.0'
info: ...
tags: [...]
paths :
  /example:
    get :
      summary: Résumé d’exemple
      description: Description d’exemple
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05
```

{% endcode %}

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/fr/api-references/extensions-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.