Administrar la visibilidad de las páginas

Controla qué endpoints de tu especificación de OpenAPI aparecen en la navegación de tu documentación

Puedes controlar qué operaciones de OpenAPI se publican como páginas de documentación y su visibilidad en la navegación. Esto es útil para endpoints internos, operaciones en desuso, funciones beta o endpoints que deberían ser accesibles mediante una URL directa pero no detectables a través de la navegación del sitio.

Si tus páginas se generan automáticamente a partir de un documento de OpenAPI, puedes gestionar la visibilidad de las páginas con las extensiones x-hidden y x-excluded.

​

x-hidden

La extensión x-hidden crea una página para un endpoint, pero la oculta de la navigation. La página solo es accesible si se navega directamente a su URL.

Algunos casos de uso comunes de x-hidden son:

• Endpoints que deseas documentar, pero no destacar.
• Páginas a las que enlazarás desde otro contenido.
• Endpoints para usuarios específicos.

​

x-excluded

La extensión x-excluded excluye por completo un endpoint de tu documentación.

Los casos de uso comunes de x-excluded son:

• Endpoints internos únicamente.
• Endpoints en desuso que no quieres documentar.
• Funcionalidades beta que aún no están listas para la documentación pública.

​

Implementación

Añade la extensión x-hidden o x-excluded bajo el método HTTP en tu especificación de OpenAPI.

Aquí tienes ejemplos de cómo usar cada propiedad en un documento de esquema de OpenAPI para un endpoint y una ruta de webhook.

"paths": {
  "/plants": {
    "get": {
      "description": "Devuelve todas las plantas de la tienda",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Devuelve todas las plantas algo secretas de la tienda",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Devuelve todas las plantas ultra secretas de la tienda (¡no publiques este endpoint!)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook para información sobre una nueva planta agregada a la tienda",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook para información algo secreta sobre una nueva planta agregada a la tienda"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook para información ultra secreta sobre una nueva planta agregada a la tienda (¡no publiques este endpoint!)"
    }
  }
}