> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/creer-du-contenu/openapi/guides/structuring-your-api-reference.md).

# Structurer votre référence d’API

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

Pour choisir entre **Une page par tag** et **Une page par opération**voir [dispositions OpenAPI](/docs/documentation/fr/creer-du-contenu/openapi/guides/openapi-layouts.md).

Cette page explique comment contrôler la navigation générée à l'aide des balises.

### Utilisez des balises pour organiser les pages générées

GitBook utilise des balises pour organiser les pages de référence API générées dans les deux dispositions.

Avec **Une page par tag**GitBook crée une page pour chaque balise. Avec **Une page par opération**GitBook crée une page pour chaque opération et utilise les balises pour regrouper ces pages dans la table des matières.

Pour regrouper des opérations liées, 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: Met à jour un animal existant.
      description: Met à jour un animal existant par son identifiant.
      operationId: updatePet
</code></pre>

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

L'ordre des pages de balises ou des groupes de balises générés correspond à l'ordre des balises dans votre OpenAPI `balises` array:

<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 créer une navigation à plusieurs niveaux, utilisez `x-parent` (ou `parent`) dans les balises pour définir la hiérarchie. Cela fonctionne avec les deux structures de page :

<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ée une table des matières comme celle-ci :

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

Si GitBook génère une page parente et que cette page n'a pas de description, il affiche une mise en page sous forme de cartes pour ses sous-pages.

### Personnalisez les titres de page, les icônes et les descriptions

Vous pouvez enrichir les pages de balises générées et les libellés de navigation avec des extensions personnalisées dans la `balises` section. 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 de compagnie sont formidables !
    # Contenu de la page
    description: Tout sur vos animaux de compagnie
```

{% endcode %}

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

Les champs de description de balise prennent en charge le Markdown GitBook, y compris [les blocs avancés](/docs/documentation/fr/creer-du-contenu/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 des 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 en charge OpenAPI 3.1, y compris les points de terminaison de webhook.

Le `webhooks` le champ fait partie d'OpenAPI 3.1, donc votre spécification doit déclarer une version OpenAPI 3.1. Vous pouvez définir des webhooks directement dans votre fichier OpenAPI, et GitBook les rend avec vos autres opérations API. Pour connaître la prise en charge des versions dans la documentation OpenAPI, voir [compatibilité OpenAPI](/docs/documentation/fr/creer-du-contenu/openapi.md#openapi-compatibility).

{% 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 lié à un 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: Retourne un statut 200 pour indiquer que les données ont été reçues avec succès
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/fr/creer-du-contenu/openapi/guides/structuring-your-api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.