Structurer votre référence d’API

Découvrez comment structurer votre référence d’API sur plusieurs pages avec des icônes et des descriptions

GitBook ne se contente pas de restituer votre spécification OpenAPI. Il vous permet de personnaliser votre référence d’API pour une meilleure clarté, une meilleure navigation et une meilleure image de marque.

Pour choisir entre Une page par tag et Une page par opération, voir les mises en page OpenAPI.

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

Utilisez des tags pour organiser les pages générées

GitBook utilise les tags pour organiser les pages de référence d’API générées dans les deux mises en page.

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

Pour regrouper les opérations liées, attribuez le même tag à chaque opération :

openapi.yaml

paths:
  /pet:
    put:
      tags :
        - animal
      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 de tags ou des groupes de tags générées correspond à l'ordre des tags dans votre OpenAPI tags array:

openapi.yaml

tags :
  - name: animal
  - name: boutique
  - name: user

Imbriquez les pages en groupes

Pour créer une navigation à plusieurs niveaux, utilisez x-parent (ou parent) dans les tags pour définir la hiérarchie. Cela fonctionne avec les deux structures de pages :

openapi.yaml

tags :
  - name: tout
  - name: animal
    x-parent: tout
  - name: boutique
    x-parent: tout

L'exemple ci-dessus crée une table des matières comme ceci :

Tout
├── Animal
└── Boutique

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

Personnalisez les titres, icônes et descriptions des pages

Vous pouvez enrichir les pages de tags générées et les libellés de navigation grâce à des extensions personnalisées dans la tags section. Tous les icônes Font Awesome sont pris en charge via x-page-icon.

openapi.yaml

tags :
  - name: animal
    # Titre de la page affiché dans la table des matières et sur la page
    x-page-title: Animal
    # 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 GitBook Blocks

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: animal
    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 %}

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

openapi.yaml

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

Documentez un endpoint de webhook

GitBook prend en charge OpenAPI 3.1, y compris les endpoints de webhook.

directement — passez chaque réponse dans webhooks 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 affiche aux côtés de vos autres opérations d'API. Pour la prise en charge des versions dans la documentation OpenAPI, voir Compatibilité OpenAPI.

openapi.yaml

---
openapi: 3.1.0 # Les webhooks sont disponibles à partir d'OpenAPI 3.1

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