# 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 des guides](https://gitbook-v2-px7y1s8bw-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/api-references/guides) pour en savoir plus sur l’utilisation des extensions OpenAPI afin de configurer votre documentation.

<details>

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

Modifier le nom affiché 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 profils des utilisateurs."
```

{% endcode %}

</details>

<details>

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

Ajoutez 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 profils des utilisateurs."
    x-page-icon: "user"
```

{% endcode %}

</details>

<details>

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

Ajouter une hiérarchie aux balises pour 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: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true
```

{% endcode %}

</details>

<details>

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

Développer 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 à 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: Lister les animaux de compagnie
      responses: [...]
      # Désactiver pour une seule opération
<strong>      x-expandAllResponses: false
</strong></code></pre>

</details>

<details>

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

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

Ajoutez-le à la racine pour l’appliquer à chaque opération. 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 de compagnie
      requestBody: [...]
      responses: [...]
      # Désactiver pour 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 à chaque opération. 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
      # Désactiver pour une seule opération
      x-enable-proxy: false
      responses:
        '200':
          description: OK
```

{% endcode %}

En savoir plus dans [Utilisation du proxy OpenAPI](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/api-references/guides/using-openapi-proxy).

</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">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>lang</code></td><td align="center">string</td><td>Langage 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>label</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: 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'
```

{% endcode %}

</details>

<details>

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

Ajoutez une description individuelle pour chacun 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 API.

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

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

{% 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: Exemple de résumé
      description: Exemple de description
      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: Exemple de résumé
      description: Exemple de description
      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 (YYYY-MM-DD)

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

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

{% endcode %}

</details>