Structurer 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 afficher votre spécification OpenAPI. Il vous permet de personnaliser votre référence API pour une meilleure clarté, navigation et image de marque.

Divisez 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, attribuez 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éorganisez les pages dans votre table des matières

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

openapi.yaml

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

Imbriquez les pages dans des 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 basée sur des cartes pour ses sous-pages.

Personnalisez les titres, icônes et descriptions des pages

Vous pouvez enrichir les pages avec des titres, des icônes et des descriptions en utilisant des extensions personnalisées dans la section tags. Tous les icônes Font Awesome sont pris en charge via x-page-icon.

openapi.yaml

tags :
  - name : pet
    # Titre de la page affiché dans la table des matières et 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

Créez des descriptions riches avec les Blocs GitBook

Les champs de description des tags prennent en charge le markdown GitBook, y compris les blocs avancés comme les onglets :

openapi.yaml

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

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

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

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

Mettez en avant les schémas

Vous pouvez mettre en avant 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 %}