# Structuration de votre référence API

GitBook fait plus que simplement rendre votre spécification OpenAPI. Il vous permet de personnaliser votre référence API pour une meilleure clarté, navigation et image de marque.

### Répartir les opérations sur plusieurs pages

Pour garder votre documentation organisée, GitBook peut diviser vos opérations API en pages séparées. Chaque page est générée à partir d’un tag dans votre spécification OpenAPI. Pour regrouper des opérations dans une page, assignez le même tag à chaque opération :

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths :
  /pet :
    put :
<strong>      tags :
</strong><strong>        - pet
</strong>      summary : Mettre à jour un animal existant.
      description : Mettre à jour un animal existant par Id.
      operationId : updatePet
</code></pre>

### Réorganiser les pages dans votre table des matières

L’ordre des pages dans GitBook correspond à l’ordre des tags dans votre tableau tags d’OpenAPI :

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags :
<strong>  - name : pet
</strong><strong>  - name : store
</strong><strong>  - name : user
</strong></code></pre>

### Imbriquer les pages en groupes

Pour construire une navigation à plusieurs niveaux, utilisez `x-parent` (ou `parent`) dans les tags pour définir la hiérarchie :

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags :
  - name : everything
  - name : pet
<strong>    x-parent : everything
</strong>  - name : store
<strong>    x-parent : everything
</strong></code></pre>

L’exemple ci‑dessus créera une table des matières qui ressemble à :

```
Everything
├── Pet
└── Store
```

Si une page n’a pas de description, GitBook affichera automatiquement une mise en page par cartes pour ses sous-pages.

### Personnaliser les titres, icônes et descriptions des pages

Vous pouvez améliorer les pages avec des titres, icônes et descriptions en utilisant des extensions personnalisées dans la section tags. Toutes les [icônes Font Awesome](https://fontawesome.com/search) sont prises en charge via `x-page-icon`.

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

```yaml
tags :
  - name : pet
    # Titre de la page affiché dans la table des matières et sur la page
    -x-page-title : Pet
    # Icône affichée dans la table des matières et à côté du titre de la page
    -x-page-icon : dog
    # Description affichée juste au‑dessus du titre
    -x-page-description : Les animaux sont incroyables !
    # Contenu de la page
    description : Tout sur vos animaux
```

{% endcode %}

### Construire des descriptions riches avec les GitBook Blocks

Les champs de description des tags prennent en charge le markdown GitBook, y compris [des blocs avancés](https://gitbook-v2-3sscp147r-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/creation-de-contenu/blocks) comme les onglets :

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

```yaml
---
tags :
  - name : pet
    description : |
      Voici le détail des animaux.

      {% tabs %}
      {% tab title="Dog" %}
      Voici les chiens
      {% endtab %}

      {% tab title="Cat" %}
      Voici les chats
      {% endtab %}

      {% tab title="Rabbit" %}
      Voici les lapins
      {% endtab %}
      {% endtabs %}
```

{% endcode %}

### Mettre en valeur les schémas

Vous pouvez mettre en valeur un schéma dans une description GitBook en utilisant le markdown GitBook. Voici un exemple qui met en avant le schéma “Pet” de la spécification “petstore” :

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

```yaml
---
tags :
  - name : pet
      description : |
          {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              L’objet Pet
          {% endopenapi-schemas %}
```

{% endcode %}

### Documenter un endpoint webhook

GitBook prend également en charge la documentation des endpoints webhook lorsqu’on utilise OpenAPI 3.1.

Vous pouvez définir vos webhooks directement dans votre fichier OpenAPI en utilisant le champ `webhooks` , qui fonctionne de manière similaire à `paths` pour les endpoints API réguliers :

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

```yaml
---
openapi : 3.1.0 # Les webhooks sont disponibles à partir d’OpenAPI 3.1

webhooks :
  newPet :
    post :
      summary : Événement nouvel animal
      description : Informations sur un nouvel animal dans le système
      requestBody :
        content :
          application/json :
            schema :
              $ref : "#/components/schemas/Pet"
      responses :
        "200":
          description : Renvoyer un statut 200 pour indiquer que les données ont été reçues avec succès
```

{% endcode %}
