Passer au contenu principal
Vous pouvez choisir quelles opérations OpenAPI sont publiées comme pages de documentation et gérer 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 bêta, ou les endpoints qui doivent être accessibles via une URL directe mais non 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é à l’aide des 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. 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 ferez des liens depuis d’autres contenus.
  • Des 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 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.

​
Mise en œuvre

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