# Structurer votre référence d'API

GitBook fait plus que simplement rendre votre spécification OpenAPI. Il vous permet de personnaliser votre référence d’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 répartir les opérations de votre API en pages séparées. Chaque page est générée à partir d’une balise dans votre spécification OpenAPI. Pour regrouper des opérations sur une page, attribuez la même balise à 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 de compagnie existant.
      description: Mettre à jour un animal de compagnie existant par identifiant.
      operationId: updatePet
</code></pre>

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

L’ordre des pages dans GitBook correspond à l’ordre des balises dans votre tableau de balises 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 des pages dans des groupes

Pour construire une navigation à plusieurs niveaux, utilisez `x-parent` (ou `parent`) dans les balises 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 à ceci :

```
Tout
├── Animal de compagnie
└── Boutique
```

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

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

Vous pouvez enrichir les pages avec des titres, des icônes et des descriptions à l’aide d’extensions personnalisées dans la section des balises. Tous les [icônes Font Awesome](https://fontawesome.com/search) sont pris 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 de compagnie sont incroyables !
    # Contenu de la page
    description: Tout sur vos animaux de compagnie
```

{% endcode %}

### Créer des descriptions riches avec les blocs GitBook

Les champs de description des balises prennent en charge le Markdown GitBook, y compris [les blocs avancés](/docs/documentation/fr/creating-content/blocks.md) comme les onglets :

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

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

      {% 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 évidence les schémas

Vous pouvez mettre en évidence un schéma dans une description GitBook en utilisant le Markdown GitBook. Voici un exemple qui met en évidence 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 point de terminaison de webhook

GitBook prend également en charge la documentation des points de terminaison de webhook lors de l’utilisation d’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 points de terminaison d’API classiques :

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

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

webhooks:
  newPet:
    post :
      summary: Nouvel événement d’animal de compagnie
      description: Informations sur un nouvel animal de compagnie 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 %}


---

# 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/guides/structuring-your-api-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.