Structuration de votre référence API

Apprenez comment structurer votre référence API sur plusieurs pages avec des icônes et des descriptions

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 :

openapi.yaml

paths :
  /pet :
    put :
      tags :
        - pet
      summary : Mettre à jour un animal existant.
      description : Mettre à jour un animal existant par Id.
      operationId : updatePet

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 :

openapi.yaml

tags :
  - name : pet
  - name : store
  - name : user

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 :

openapi.yaml

tags :
  - name : everything
  - name : pet
    x-parent : everything
  - name : store
    x-parent : everything

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 sont prises en charge via x-page-icon.

openapi.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

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 comme les onglets :

openapi.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 %}

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” :

openapi.yaml

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

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 :

openapi.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