Contenido personalizado

Personaliza el contenido para los visitantes identificados sin dejar de mantener tu documentación pública. Algunos ejemplos de personalización son rellenar previamente claves de API, mostrar contenido específico para el plan o el rol de un usuario y filtrar el contenido de referencia de la API en función de la pertenencia a grupos. La personalización usa una sesión compartida, JWT u OAuth para identificar a los visitantes sin restringir el acceso a tus páginas.

Método	Ideal para	Identificación del visitante
Sesión compartida	Documentación y una aplicación existente que pueden compartir una sesión de navegador	Mintlify solicita los datos del usuario a tu Info API con las cookies de sesión del visitante.
JWT	Un flujo de inicio de sesión existente que puede firmar los datos de usuario de Mintlify	Tu flujo de inicio de sesión redirige al visitante de vuelta con un JWT firmado.
OAuth	Un proveedor OAuth 2.0 existente	Mintlify completa un flujo OAuth y solicita los datos del usuario a tu Info API.

Configurar la personalización

Habilita la personalización en la página Add-ons de tu dashboard. La personalización es mutuamente excluyente con la autenticación completa. La autenticación con JWT y OAuth incluye las funciones de personalización.

Ve a la página Add-ons de tu dashboard.
En la sección Personalization, selecciona sesión compartida, JWT u OAuth.
Configura el método de personalización elegido.
Haz clic en Save changes.

Sesión compartida

La sesión compartida reutiliza la sesión existente del visitante en tu aplicación, de modo que no necesita iniciar sesión de nuevo en tu sitio de Mintlify.

Selecciona Shared session en la configuración de Personalization.
Introduce una Info API URL que devuelva los datos de usuario del visitante actual.
Opcionalmente, introduce una Login URL. Mintlify muestra un enlace de inicio de sesión cuando la Info API no devuelve datos de usuario.
Haz clic en Save changes.

Mintlify envía una solicitud GET a la Info API desde el navegador del visitante con las credenciales incluidas. Devuelve una respuesta JSON correcta para un visitante identificado:

User data response

{
  "expiresAt": 1893456000,
  "content": {
    "firstName": "Jane",
    "plan": "Enterprise"
  },
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

Para un visitante sin una sesión válida, devuelve una respuesta no exitosa, como 401. Mintlify deja al visitante sin identificar y mantiene disponible el contenido público. Si la Info API está en un origen distinto al de tu documentación, configúrala para permitir solicitudes entre orígenes con credenciales desde el origen exacto de la documentación. No uses un origen comodín con credenciales. Evita que los navegadores y las cachés intermedias almacenen los datos de usuario devolviendo Cache-Control: private, no-store.

Los valores de apiPlaygroundInputs están disponibles en el navegador para que el área de pruebas de la API pueda enviarlos. Devuelve credenciales de corta duración y con el alcance adecuado, y evita exponer un token de sesión privilegiado de la aplicación cuando exista un token específico para la documentación.

JWT y OAuth

La personalización con JWT y OAuth usa el mismo formato de datos de usuario que la sesión compartida, pero no restringe el acceso a tu documentación. Configura estos métodos en Add-ons, no en Authentication. Para la personalización con JWT:

Introduce la URL de tu flujo de inicio de sesión existente.
Haz clic en Save changes.
Haz clic en Generate new key y almacena de forma segura la clave privada descargada.
En tu flujo de inicio de sesión, crea un JWT que contenga los datos de usuario del visitante identificado y fírmalo con la clave privada generada usando el algoritmo ES256.
Redirige al visitante a una página de tu sitio de documentación con el JWT firmado como fragmento de la URL. Por ejemplo, https://docs.example.com/get-started#{SIGNED_JWT}. Para una subruta personalizada, incluye la subruta en esta URL.

Establece el claim exp del JWT con una duración corta de 10 segundos o menos. Usa el campo expiresAt de los datos de usuario para controlar durante cuánto tiempo Mintlify almacena los datos de personalización. Para la personalización con OAuth:

Introduce tu URL de autorización, ID de cliente, scopes, URL de token, URL de la Info API y cualquier ajuste opcional, y luego haz clic en Save changes. La personalización con OAuth usa el flujo de código de autorización con Proof Key for Code Exchange (PKCE) y no requiere un secreto de cliente.
Copia la Redirect URL del dashboard y agrégala como URL de redirección autorizada en tu proveedor de OAuth.
Configura la Info API para aceptar una solicitud GET con el token de acceso de OAuth en el encabezado Authorization: Bearer <access_token> y devolver los datos de usuario.

La ruta de redirección de OAuth es /mintlify-oauth-callback. En una subruta personalizada, el dashboard incluye la subruta en la URL de redirección. Mintlify intercambia el código de autorización y solicita los datos del usuario desde el navegador del visitante. Si el endpoint de token o de la Info API está en un origen distinto al de tu documentación, configúralo para permitir solicitudes entre orígenes desde el origen exacto de la documentación. La Info API debe permitir el encabezado de solicitud Authorization.

Relleno automático de claves de la API

Rellena automáticamente los campos del área de pruebas de la API con valores específicos de cada usuario devolviendo nombres de campos coincidentes en tus datos de usuario. Incluye esos valores en el campo apiPlaygroundInputs de tus datos de usuario.

{
  "apiPlaygroundInputs": {
    "header": { "X-API-Key": "user_api_key_123" },
    "server": { "subdomain": "acme" }
  }
}

Los nombres de los campos deben coincidir con los definidos en tu especificación de OpenAPI. Mintlify aplica únicamente los valores que coinciden con el esquema de seguridad del endpoint actual.

Contenido MDX dinámico

Muestra contenido en función de la información del usuario, como el nombre, el plan u organización, utilizando la variable user en tus páginas MDX. Incluye datos personalizados en el campo content de tus datos de usuario.

{
  "content": {
    "firstName": "Jane",
    "company": "Acme Corp",
    "plan": "Enterprise"
  }
}

Utiliza estos valores en tu MDX.

¡Bienvenido de nuevo, {user.firstName}! Tu plan {user.plan} incluye 100 espacios para miembros de tu organización {user.company}.

Para el renderizado condicional basado en datos de usuario, usa la variable user en componentes JSX.

{
  user.plan === 'enterprise'
    ? <>Contacta con tu administrador para habilitar esta función.</>
    : <>Consulta <a href="https://yoursite.com/pricing">precios</a> para obtener información sobre la actualización.</>
}

La variable user es un objeto vacío para los usuarios que no han iniciado sesión. Utiliza el encadenamiento opcional en todas las propiedades de user para evitar errores. Por ejemplo, {user.org?.plan} en lugar de {user.org.plan}.

Para leer el mismo objeto de usuario desde un archivo JavaScript personalizado, utiliza window.mintlify.user y escucha el evento mintlify:user.

Visibilidad de páginas

Controla qué páginas aparecen en la navegación según los grupos de usuarios añadiendo groups al frontmatter de la página.

Con la personalización, groups controla la visibilidad, pero no restringe el acceso a una página. Un visitante todavía puede abrir una página filtrada por grupo navegando directamente a su URL. Usa la autenticación para restringir el acceso a contenido sensible.

---
title: "Configuración de administrador"
groups: ["admin"]
---

Filtrado de contenido de OpenAPI

Filtra el contenido de referencia de tu API en función de los grupos de usuarios mediante la extensión x-mint en tu especificación de OpenAPI. Puedes filtrar endpoints completos, propiedades individuales de esquemas, variantes de oneOf y valores de enum.

Filtrar endpoints

Agrega x-mint.groups a una operación o ruta para mostrar el endpoint en la navegación solo a grupos de usuarios específicos. Con la personalización independiente, los usuarios que no pertenezcan a los grupos indicados aún pueden abrir la página del endpoint mediante su URL directa.

{
  "paths": {
    "/billing": {
      "get": {
        "summary": "Obtener detalles de facturación",
        "x-mint": {
          "groups": ["admin", "billing"]
        },
        "responses": {
          "200": {
            "description": "Detalles de facturación"
          }
        }
      }
    }
  }
}

{
  "paths": {
    "x-mint": {
      "groups": ["admin", "billing"]
    },
    "/billing": {
      "get": {
        "summary": "Obtener detalles de facturación",
      }
    },
    "/users": {
      "get": {
        "summary": "Obtener detalles de usuarios",
      }
    }
  }
}

Filtrar propiedades del esquema

Agrega x-mint.groups a propiedades individuales dentro de los cuerpos de las solicitudes, parámetros o respuestas. Las propiedades sin x-mint.groups siguen siendo visibles para todos los usuarios.

Restricted property

{
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "internal_id": {
            "type": "string",
            "x-mint": {
              "groups": ["admin"]
            }
          }
        }
      }
    }
  }
}

En este ejemplo, todos los usuarios pueden ver la propiedad name. Solo los usuarios del grupo admin pueden ver la propiedad internal_id.

Filtrar variantes de oneOf

Agrega x-mint.groups a las opciones individuales de oneOf para restringir qué variantes de esquema puede ver un usuario.

Restricted oneOf variant

{
  "schema": {
    "oneOf": [
      {
        "title": "Enterprise config",
        "type": "object",
        "x-mint": {
          "groups": ["enterprise"]
        },
        "properties": {
          "sso_enabled": { "type": "boolean" }
        }
      },
      {
        "title": "Standard config",
        "type": "object",
        "properties": {
          "notifications": { "type": "boolean" }
        }
      }
    ]
  }
}

Filtrar valores de enum

Usa la extensión x-mint-enum para restringir valores individuales de enum por grupo. Enumera cada valor restringido como una key, con sus grupos permitidos como value. Los valores de enum que no estén listados en x-mint-enum son visibles para todos los usuarios.

Restricted enum values

{
  "type": "string",
  "enum": ["free", "pro", "enterprise"],
  "x-mint-enum": {
    "pro": ["pro", "enterprise"],
    "enterprise": ["enterprise"]
  }
}

En este ejemplo, todos los usuarios ven free. Los usuarios de los grupos pro o enterprise ven pro. Solo los usuarios del grupo enterprise ven enterprise.

x-mint-enum es una extensión independiente de nivel superior en el objeto de esquema y no está anidada dentro de x-mint.

Formato de datos de usuario

Tu sistema de identificación o autenticación devuelve datos de usuario que gestionan la personalización. Los campos groups, content y apiPlaygroundInputs descritos en esta página forman parte del objeto de datos de usuario. Para obtener el formato completo de los datos de usuario y la referencia de campos, consulta Formato de datos de usuario.

Comportamiento de cierre de sesión

El cierre de sesión se realiza en el cliente. Cuando los usuarios hacen clic en el botón de cerrar sesión, Mintlify borra los datos de la sesión almacenados en el navegador. Para limitar el tiempo durante el cual persisten los datos de personalización, configura el campo expiresAt en los datos de usuario.

Primeros pasos

Crear contenido

Administra tu sitio

Agente

Assistant

Contenido preparado para agentes

Búsqueda y SEO

Documentar APIs

Integraciones

Referencia

Contenido personalizado

Configurar la personalización

Sesión compartida

JWT y OAuth

Relleno automático de claves de la API

Contenido MDX dinámico

Visibilidad de páginas

Filtrado de contenido de OpenAPI

Filtrar endpoints

Filtrar propiedades del esquema

Filtrar variantes de oneOf

Filtrar valores de enum

Formato de datos de usuario

Comportamiento de cierre de sesión

​Configurar la personalización

​Sesión compartida

​JWT y OAuth

​Relleno automático de claves de la API

​Contenido MDX dinámico

​Visibilidad de páginas

​Filtrado de contenido de OpenAPI

​Filtrar endpoints

​Filtrar propiedades del esquema

​Filtrar variantes de oneOf

​Filtrar valores de enum

​Formato de datos de usuario

​Comportamiento de cierre de sesión

Configurar la personalización

Sesión compartida

JWT y OAuth

Relleno automático de claves de la API

Contenido MDX dinámico

Visibilidad de páginas

Filtrado de contenido de OpenAPI

Filtrar endpoints

Filtrar propiedades del esquema

Filtrar variantes de oneOf

Filtrar valores de enum

Formato de datos de usuario

Comportamiento de cierre de sesión