Gestion de la visibilité des pages

Vous pouvez décider quelles opérations OpenAPI sont publiées en tant que pages de documentation et contrôler leur visibilité dans la navigation. C’est utile pour les endpoints réservés à un usage interne, les opérations obsolètes, les fonctionnalités en bêta, ou les endpoints qui doivent rester accessibles via une URL directe sans être visibles dans la navigation du site. Si vos pages sont générées automatiquement à partir d’un document OpenAPI, vous pouvez gérer leur visibilité avec les extensions x-hidden et x-exclus.

`x-hidden`

L’extension x-hidden génère une page pour un endpoint, mais la retire de la navigation. La page n’est accessible qu’en se rendant directement sur son URL. Cas d’usage courants de x-hidden :

Endpoints que vous souhaitez documenter sans les mettre en avant.
Pages vers lesquelles vous ferez des liens depuis d’autres contenus.
Endpoints destinés à des utilisateurs spécifiques.

`x-excluded`

L’extension x-excluded exclut entièrement un endpoint de votre documentation. Cas d’usage courants de x-excluded :

Endpoints internes uniquement.
Endpoints obsolètes que vous ne souhaitez pas documenter.
Fonctionnalités bêta qui ne sont pas prêtes pour la documentation publique.

Implémentation

Ajoutez l’extension x-hidden ou x-excluded sous la méthode HTTP dans votre spécification OpenAPI. Voici des exemples d’utilisation de chaque propriété dans un document de schéma OpenAPI pour une API endpoint et un chemin de webhook.

"paths": {
  "/plants": {
    "get": {
      "description": "Renvoie toutes les plantes de la boutique",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Renvoie toutes les plantes un peu secrètes de la boutique",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Renvoie toutes les plantes top secrètes de la boutique (ne publiez pas cet endpoint !)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook pour des informations sur une nouvelle plante ajoutée au magasin",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook pour des informations quelque peu confidentielles sur une nouvelle plante ajoutée au magasin",
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook pour des informations strictement confidentielles sur une nouvelle plante ajoutée au magasin (ne publiez pas cet endpoint !)"
    }
  }
}

Démarrage

Configuration de base

Optimisation de l’IA

Composants

Pages API

Authentification et personnalisation

Guides

Intégrations

Contrôle de version et CI/CD

Gestion de la visibilité des pages

`x-hidden`

`x-excluded`

Implémentation

​x-hidden

​x-excluded

​Implémentation

`x-hidden`

`x-excluded`

Implémentation