Vous pouvez décider quelles opérations OpenAPI sont publiées sous forme de pages de documentation et contrôler 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 par URL directe sans être repérables via 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 se rendant directement sur son URL. Les cas d’usage courants de x-hidden sont :
  • Des endpoints que vous souhaitez documenter sans les mettre en avant.
  • Des pages vers lesquelles vous ferez des liens depuis d’autres contenus.
  • Des endpoints destinés à des utilisateurs spécifiques.

​
x-excluded

L’extension x-excluded exclut complètement 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.

​
Mise en œuvre

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 un endpoint et un chemin de webhook. 
"paths": {
  "/plants": {
    "get": {
      "description": "Returns all plants from the store",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Returns all somewhat secret plants from the store",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook for information about a new plant added to the store",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook for somewhat secret information about a new plant added to the store"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
    }
  }
}