Mises en page OpenAPI

Choisissez entre une page par tag et une page par opération pour votre référence d’API

Lorsque vous insérez un Référence OpenAPI, GitBook peut organiser les opérations de deux façons.

Choisissez la mise en page qui correspond à la façon dont vous souhaitez que les utilisateurs parcourent votre API.

Accédez à ce paramètre

Pour choisir une mise en page :

1. Dans votre section, cliquez sur Ajouter... → Référence OpenAPI. Vous pouvez également modifier une référence OpenAPI existante.
2. Choisissez votre spécification OpenAPI.
3. Dans Structure de la page, sélectionnez Une page par tag ou Une page par opération.

Pour le flux de configuration complet, voir Insérer une référence API dans votre documentation.

Mises en page disponibles

GitBook prend en charge deux mises en page :

• Une page par tag crée une page pour chaque tag. Chaque page répertorie toutes les opérations associées à ce tag.
• Une page par opération crée une page pour chaque opération. GitBook regroupe ces pages par tag dans la table des matières.

Exemple d’entrée

Les deux mises en page partent des mêmes données OpenAPI :

openapi.yaml

paths:
  /users :
    get:
      tags :
        - users
      résumé : Lister les utilisateurs
    post:
      tags :
        - users
      résumé : Créer un utilisateur

Une page par tag

Utilisez cette mise en page lorsque chaque tag représente une section claire de votre API.

Cela fonctionne bien lorsque vous souhaitez des pages récapitulatives, moins d’éléments dans la navigation et des points de terminaison associés sur la même page.

Avec cette mise en page, les deux opérations apparaissent sur la même page générée pour le users tag.

Une page par opération

Utilisez cette mise en page lorsque vous souhaitez des liens directs vers des points de terminaison individuels.

Cela fonctionne bien pour les grandes API, ou lorsque chaque point de terminaison a besoin de sa propre page dans la navigation.

Avec cette mise en page, GitBook crée une page pour GET /users et une page pour POST /users. Les deux pages apparaissent sous le users groupe de tags.

Recommandation rapide

Choisissez Une page par tag pour les petites API, ou lorsque chaque tag correspond à une section claire.

Choisissez Une page par opération pour les grandes API, ou lorsque vous souhaitez une page dédiée pour chaque point de terminaison.

Contrôlez la navigation générée

Dans les deux mises en page, GitBook utilise vos tags OpenAPI pour organiser la référence.

Pour contrôler l’ordre, la hiérarchie, les titres des pages, les icônes et les descriptions, consultez Structurer votre référence API.