Incrustación de valores en las URL de documentación

Mejore la colaboración incrustando valores específicos de parámetros y variables directamente en las URL de documentación compartidas. De forma predeterminada, los documentos compartidos contienen únicamente especificaciones de API. Esta función le permite compartir valores prerrellenados, lo que facilita a los usuarios probar endpoints con configuraciones específicas.

Comportamiento de los parámetros

Los valores de parámetros pasados mediante la URL se comportan de forma diferente según su tipo:

Variables de entorno: Los valores establecidos a través de la URL se aplican globalmente en todos los endpoints dentro del documento. Persisten al navegar entre endpoints o al abrir nuevas pestañas, y permanecen activos hasta que se sobrescriban explícitamente o se cambien manualmente.

Parámetros de petición (consulta, ruta, cuerpo, encabezado, cookie): Estos valores se limitan al endpoint específico al que se accede mediante la URL y no persisten al navegar a otros endpoints.

Pasar valores de parámetros

Hay dos métodos disponibles para incrustar valores de parámetros: Modo simple y Modo complejo. El modo simple es más conciso y no requiere codificación de URL, pero no puede gestionar caracteres de corchetes. El modo complejo admite todos los caracteres, pero requiere la codificación de URL de los datos de parámetros.

Modo simple

El modo simple usa el formato parameterType[parameterName]=value.

Ejemplo:

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?environment[access_token]=example_value&query[locale]=en-US

Tipo de parámetro	Formato del valor del parámetro	Descripción	Comportamiento
Parámetros de consulta	`query[xxx]=yyy`		Solo el endpoint actual
Parámetros de ruta	`path[xxx]=yyy`		Solo el endpoint actual
Parámetros de cuerpo	`body[xxx]=yyy`	Para tipos de cuerpo `form-data` o `x-www-form-urlencoded`	Solo el endpoint actual
Parámetros de cuerpo	`body=yyy`	Para otros tipos de cuerpo (p. ej., JSON sin procesar, XML)	Solo el endpoint actual
Parámetros de encabezado	`header[xxx]=yyy`		Solo el endpoint actual
Parámetros de cookie	`cookie[xxx]=yyy`		Solo el endpoint actual
Variables de entorno	`environment[xxx]=yyy`	Establece el valor en el entorno predeterminado.	Persiste entre endpoints

Modo complejo

El modo complejo pasa un objeto JSON codificado para URL como valor del parámetro params. Este objeto JSON debe codificarse usando encodeURIComponent. En JavaScript, esto puede lograrse con: encodeURIComponent(JSON.stringify({"query":["id",1]})).

JSON de ejemplo (antes de la codificación):

{
    "query": [
        ["id", "value1"],
        ["id", "value2"],
        ["key2", "value3"]
    ],
    "path": [
        ["key1", "value1"],
        ["key2", "value2"]
    ],
    "body": [
        ["aaa", "value1"],
        ["key2", "value2"]
    ],
    "header": [
        ["testHeader", "value1"],
        ["key2", "value2"]
    ],
    "cookie": [
        ["testCookie", "value1"],
        ["key2", "value2"]
    ],
    "environment": [
        ["access_token", "example_value"],
        ["projectId", "1"]
    ]
}

URL de ejemplo (después de la codificación):

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?params=%7B%22query%22%3A%5B%5B%22id%22%2C%22value1%22%5D%2C%5B%22id%22%2C%22value2%22%5D%2C%5B%22key2%22%2C%22value3%22%5D%5D%2C%22path%22%3A%5B%5B%22key1%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22body%22%3A%5B%5B%22aaa%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22header%22%3A%5B%5B%22testHeader%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22cookie%22%3A%5B%5B%22testCookie%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22environment%22%3A%5B%5B%22access_token%22%2C%22example_value%22%5D%2C%5B%22projectId%22%2C%221%22%5D%5D%7D

Tipo de parámetro	Valor del parámetro	Descripción	Comportamiento
Parámetros de consulta	`query`	Un arreglo de pares clave-valor.	Solo el endpoint actual
Parámetros de ruta	`path`	Un arreglo de pares clave-valor.	Solo el endpoint actual
Parámetros de cuerpo	`body`	Un arreglo de pares clave-valor para `form-data` o `x-www-form-urlencoded`; una cadena para otros tipos de cuerpo.	Solo el endpoint actual
Parámetros de encabezado	`header`	Un arreglo de pares clave-valor.	Solo el endpoint actual
Parámetros de cookie	`cookie`	Un arreglo de pares clave-valor.	Solo el endpoint actual
Variables de entorno	`environment`	Un arreglo de pares clave-valor. Establece valores en el entorno predeterminado.	Persiste entre endpoints

Pasar variables de entorno

Para establecer automáticamente variables de entorno para un usuario, inclúyalas en la URL. Estas variables persistirán en todos los endpoints del documento.

Ejemplos:

https://openapi.apidog.io/api-7312738-run?environment[access_token]=example_value

Mejor práctica

Las variables de entorno persisten entre endpoints, mientras que otros tipos de parámetros (consulta, ruta, cuerpo, encabezado, cookie) se limitan al endpoint específico en la URL. Este método es el más adecuado para compartir valores reutilizables entre múltiples endpoints.

Incrustación de valores en las URL de documentación

Comportamiento de los parámetros#

Pasar valores de parámetros#

Modo simple#

Modo complejo#

Pasar variables de entorno#

Comportamiento de los parámetros

Pasar valores de parámetros

Modo simple

Modo complejo

Pasar variables de entorno