Passer au contenu principal
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 !)"
    }
  }
}