Documentación personalizada

Puedes personalizar la documentación para tus lectores, de modo que ya no tengan que saltar constantemente entre distintas fuentes para encontrar la información que necesitan.

Elementos que puedes mostrar en tu documentación y que se pueden personalizar:

• ID de usuario,

• Nombre de usuario,

• Claves de API,

• Versión de la API que están usando actualmente,

• Plan que tienen contratado,

• Sus permisos...

Cómo personalizar la documentación

Puedes usar variables para personalizar la documentación para tus lectores. Por ejemplo, si abriste esta documentación a través de nuestro Help & Support, encontrarás tu nombre en la primera página y también aquí.

Las variables se pueden inyectar en la documentación de dos maneras:

• Enviando a tus lectores a una URL de la documentación con ciertos parámetros de consulta.

• Escribiendo una cookie.

• Usando un flujo de inicio de sesión personalizado, o un enlace firmado en un sitio de documentación público.

Cuando se inyectan las variables, la documentación mostrará la información relevante para el lector.

Personalización mediante URL

Las variables se pueden inyectar en una página a través de la URL. Puedes proporcionar las variables de dos maneras:

• Texto sin cifrar: agrégalo en un vars de la URL. Por ejemplo, ?vars={"user":{"name": "John"}}

• Base64: agrégalo en un hvars de la URL. Por ejemplo, ?hvars=eyJ1c2VyIjp7Im5hbWUiOiJKb2huIn19

Como ejemplo, si cargas esta documentación desde este enlace:

https://docs.developerhub.io/?vars={"user":{"name": "John"}}

Entonces verás que se te da la bienvenida como una persona llamada John.

Personalización mediante cookie

Puedes personalizar (inyectar variables) estableciendo una cookie que tu sitio de documentación pueda leer. Usar una cookie para la personalización es preferible a usar la personalización mediante URL, ya que las variables no serían visibles en la barra de direcciones.

Se espera que la cookie se escriba fuera del sitio de documentación. Por ejemplo, si eres propietario de pied-piper.com y tu sitio de documentación está en pied-piper.com/docs, escribirías la cookie en pied-piper.com, que también se podrá leer en pied-piper.com/docs.

Las cookies solo se pueden leer dentro del mismo dominio raíz, independientemente del subdominio. Por ejemplo, puedes escribir una cookie en pied-piper.com y hacer que se pueda leer en docs.pied-piper.com y en pied-piper.com/docs. Sin embargo, si tu sitio de documentación está en un dominio raíz diferente, como pied-docs.com, debes personalizar mediante URL o inicio de sesión personalizado.

Para inyectar variables mediante una cookie, incluye lo siguiente en la cookie:

Por ejemplo, para escribir una cookie de este tipo usando JavaScript:

Estándar para los detalles del usuario

Para personalizar la documentación, proponemos este estándar para cualquier función que tengamos o que podamos crear en el futuro. Recomendamos que uses la siguiente estructura JSON: