# 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 d’extensions différentes que vous pouvez ajouter à votre spécification OpenAPI.

Rendez-vous dans notre [section des guides](https://gitbook-open-v2-preview.gitbook.workers.dev/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>

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

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

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

Ajoute 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` .
{% 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>

Affiche ou masque 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-enable-proxy</code></summary>

Faites passer les requêtes « Tester » 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 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 santé
      # Exclure une seule opération
      x-enable-proxy: false
      responses:
        '200':
          description: OK
```

{% endcode %}

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

</details>

<details>

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

Affiche, masque ou inclut 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>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>

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

Masque 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: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true
```

{% endcode %}

</details>

<details>

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

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

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

Ajoute 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: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05
```

{% endcode %}

</details>