Variables

Las variables de proyecto te ayudan a etiquetar las partes repetitivas de tu documentación para poder cambiarlas de forma centralizada en un solo lugar. También te permiten personalizar la documentación para tus lectores.


Por ejemplo, es posible que quieras que toda la referencia de la API use la última versión en sus solicitudes de ejemplo. Sin variables, tendrías que subir una nueva referencia con cambios en cada solicitud de ejemplo cada vez que actualices la versión.

Una de las solicitudes de ejemplo podría verse así:

var options = {
"method": "GET",
"url": "https://api.your-service.com/user",
"body": {
"version": "2019-10-12", // <-- change this to "%latest_version%"
"id": 512
}
};

request(options, function (error, response, body) {
if (error) throw new Error(error);

console.log(body);
});

Con las variables, podrás cambiar de forma centralizada el valor de la versión, ahorrando tiempo y esfuerzo.

¿Cómo usar las variables de proyecto?

Se necesitan dos cosas para configurar las variables de proyecto:

  • Añade un objeto JSON con las variables que estarán disponibles en la documentación.

  • Inserta referencias a las variables en la documentación envolviéndolas entre signos de porcentaje, así: %variable%.

¿Dónde puedes usar las variables de proyecto?

Las variables de proyecto se pueden insertar en:

  • Contenido de páginas y bloques.

  • Descripciones de la referencia de API.

  • Enlaces externos del índice.

  • JavaScript personalizado.

  • Diseño predeterminado de la página de inicio.

  • HTML personalizado en las páginas de inicio.

Editar las variables de proyecto

Para editar las variables de proyecto, haz lo siguiente:

  • Abre Project Settings → Content → Project Variables.

  • Introduce un objeto JSON que defina todas tus variables. Por ejemplo:

{
"project_name": "Xyz",
"versions": {
"latest_version": "1.54.2"
}
}

Uso de las variables de proyecto en las referencias

Para usar variables de proyecto en una referencia de API, reemplaza todas las apariciones de la variable por la referencia a la variable. Por ejemplo, una propiedad de definición podría ser:

version:
type: string
description: Version of the API
example: "%versions.last_version%"

O para reemplazar una variable llamada subdomain en la URL del servidor:

servers:
- url: https://{subdomain}.developerhub.io/api/v1
variables:
subdomain:
default: "%subdomain%"
Advertencia

Ten en cuenta que YAML requiere usar comillas dobles para escapar una cadena que contiene un signo de porcentaje.

Uso de las variables de proyecto en scripts

Para usar variables de proyecto en scripts, primero debes configurar el proyecto para exponer las variables mediante el objeto window.vars. Para ello:

  • Abre Project Settings → Content → Project Variables.

  • Marca Expose variables in Javascript.

  • Haz clic en Save changes en el menú superior.

En la documentación publicada, una vez que se cargue el proyecto, podrás acceder a las variables (definidas en Project e inyectadas mediante la personalización) a través de window.vars.

Personalización de la documentación

Puedes usar variables para personalizar la documentación. Obtén más información en Documentación personalizada.

Limitaciones conocidas

  • Las variables no funcionan como HREF de los enlaces.


inline-blocks
  Última actualización