Gérer la visibilité des pages

Pour les endpoints réservés à un usage interne, les opérations obsolètes, les fonctionnalités bêta, ou les endpoints qui doivent être accessibles via une URL directe mais non repérables via la navigation du site, vous pouvez contrôler quelles opérations OpenAPI sont publiées en tant que pages de documentation ainsi que leur visibilité dans la navigation.

Si vos pages sont générées automatiquement à partir d’un document OpenAPI, gérez leur visibilité avec les extensions x-hidden et x-excluded.

L’extension x-hidden crée une page pour un endpoint, mais la masque dans la navigation. La page n’est accessible qu’en accédant directement à son URL.

Voici des cas d’usage courants de x-hidden :

• Des endpoints que vous souhaitez documenter sans les mettre en avant.
• Des pages vers lesquelles vous faites des liens depuis d’autres contenus.
• Des endpoints destinés à des utilisateurs spécifiques.

L’extension x-excluded exclut entièrement un endpoint de votre documentation.

Cas d’usage courants de x-excluded :

• Endpoints réservés à un usage interne.
• Endpoints obsolètes que vous ne souhaitez pas documenter.
• Fonctionnalités bêta pas encore prêtes pour une documentation publique.

Ajoutez l’extension x-hidden ou x-excluded sous la méthode HTTP dans votre spécification OpenAPI.

Voici des exemples montrant comment utiliser chaque propriété dans un document de schéma OpenAPI pour une route d’endpoint et un chemin de webhook.

"paths": {
  "/plants": {
    "get": {
      "description": "Renvoie toutes les plantes du magasin",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Renvoie toutes les plantes semi-confidentielles du magasin",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Renvoie toutes les plantes hautement confidentielles du magasin (ne pas publier ce endpoint !)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook pour les informations concernant une nouvelle plante ajoutée au catalogue",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook pour les informations semi-confidentielles concernant une nouvelle plante ajoutée au catalogue"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook pour les informations hautement confidentielles concernant une nouvelle plante ajoutée au catalogue (ne pas publier ce endpoint !)"
    }
  }
}