Passer au contenu principal
Vous pouvez décider quelles opérations OpenAPI sont publiées en tant que pages de documentation et régler leur visibilité dans la navigation. C’est utile pour des endpoints internes, des opérations obsolètes, des fonctionnalités bêta, ou des endpoints qui doivent rester accessibles via une URL directe sans être trouvables depuis 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-excluded.

​
x-hidden

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. Les cas d’usage courants de x-hidden sont :
  • Les endpoints que vous souhaitez documenter, sans les mettre en avant.
  • Les pages vers lesquelles vous créerez des liens depuis d’autres contenus.
  • Les endpoints destinés à des utilisateurs spécifiques.

​
x-excluded

L’extension x-excluded exclut entièrement un endpoint de votre documentation. Les cas d’usage courants de x-excluded sont :
  • Endpoints réservés à un usage interne.
  • Endpoints obsolètes que vous ne souhaitez pas documenter.
  • Fonctionnalités bêta qui ne sont pas prêtes pour une 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 un 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 quelque peu secrètes du magasin",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Renvoie toutes les plantes ultra-secrètes du magasin (ne pas publier ce point de terminaison !)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook pour les informations concernant une nouvelle plante ajoutée au magasin",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook pour des informations quelque peu confidentielles concernant une nouvelle plante ajoutée au magasin"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook pour des informations ultra-confidentielles concernant une nouvelle plante ajoutée au magasin (ne pas publier ce point de terminaison !)"
    }
  }
}
⌘I