mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
e42653a294
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
92 lines
3.2 KiB
Plaintext
92 lines
3.2 KiB
Plaintext
---
|
||
title: "Gérer la visibilité des pages"
|
||
description: "Contrôlez quels endpoints d’API apparaissent dans la navigation de votre documentation."
|
||
keywords: ["x-hidden", "x-excluded", "masquer des endpoints", "visibilité des pages", "endpoints internes"]
|
||
---
|
||
|
||
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`.
|
||
|
||
<div id="x-hidden">
|
||
## `x-hidden`
|
||
</div>
|
||
|
||
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.
|
||
|
||
<div id="x-excluded">
|
||
## `x-excluded`
|
||
</div>
|
||
|
||
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.
|
||
|
||
<div id="implementation">
|
||
## Implémentation
|
||
</div>
|
||
|
||
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.
|
||
|
||
```json Endpoint example {11, 19}
|
||
"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": { /*...*/ }
|
||
}
|
||
}
|
||
},
|
||
```
|
||
|
||
```json Webhook example {9, 15}
|
||
"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 !)"
|
||
}
|
||
}
|
||
}
|
||
```
|