Incorporação de valores em URLs de documentação

Aprimore a colaboração incorporando valores específicos de parâmetros e variáveis diretamente em URLs de documentação compartilhada. Por padrão, documentos compartilhados contêm apenas especificações de API. Este recurso permite que você compartilhe valores pré-preenchidos, facilitando para que os usuários testem endpoints com configurações específicas.

Comportamento dos parâmetros

Os valores de parâmetros passados pela URL se comportam de maneira diferente com base em seu tipo:

Variáveis de ambiente: valores definidos por meio da URL são aplicados globalmente a todos os endpoints dentro do documento. Eles persistem ao navegar entre endpoints ou abrir novas abas, permanecendo ativos até serem explicitamente substituídos ou alterados manualmente

Parâmetros da requisição (Query, Path, Body, Header, Cookie): esses valores são limitados ao endpoint específico acessado por meio da URL e não persistem ao navegar para outros endpoints

Passagem de valores de parâmetros

Dois métodos estão disponíveis para incorporar valores de parâmetros: Modo Simples e Modo Complexo. O Modo Simples é mais conciso e não exige codificação de URL, mas não consegue lidar com caracteres de colchetes. O Modo Complexo oferece suporte a todos os caracteres, mas exige a codificação de URL dos dados de parâmetros.

Modo Simples

O Modo Simples usa o formato parameterType[parameterName]=value.

Exemplo:

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

Tipo de parâmetro	Formato do valor do parâmetro	Descrição	Comportamento
Parâmetros de query	`query[xxx]=yyy`		Apenas endpoint atual
Parâmetros de path	`path[xxx]=yyy`		Apenas endpoint atual
Parâmetros de corpo	`body[xxx]=yyy`	Para tipos de corpo `form-data` ou `x-www-form-urlencoded`	Apenas endpoint atual
Parâmetros de corpo	`body=yyy`	Para outros tipos de corpo (por exemplo, JSON bruto, XML)	Apenas endpoint atual
Parâmetros de cabeçalho	`header[xxx]=yyy`		Apenas endpoint atual
Parâmetros de cookie	`cookie[xxx]=yyy`		Apenas endpoint atual
Variáveis de ambiente	`environment[xxx]=yyy`	Define o valor no ambiente padrão.	Persiste entre endpoints

Modo Complexo

O Modo Complexo passa um objeto JSON codificado para URL como o valor do parâmetro params. Esse objeto JSON deve ser codificado usando encodeURIComponent. Em JavaScript, isso pode ser feito com: encodeURIComponent(JSON.stringify({"query":["id",1]})).

JSON de exemplo (antes da codificação):

{
    "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 exemplo (após a codificação):

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 do parâmetro	Descrição	Comportamento
Parâmetros de query	`query`	Um array de pares chave-valor.	Apenas endpoint atual
Parâmetros de path	`path`	Um array de pares chave-valor.	Apenas endpoint atual
Parâmetros de corpo	`body`	Um array de pares chave-valor para `form-data` ou `x-www-form-urlencoded`; uma string para outros tipos de corpo.	Apenas endpoint atual
Parâmetros de cabeçalho	`header`	Um array de pares chave-valor.	Apenas endpoint atual
Parâmetros de cookie	`cookie`	Um array de pares chave-valor.	Apenas endpoint atual
Variáveis de ambiente	`environment`	Um array de pares chave-valor. Define valores no ambiente padrão.	Persiste entre endpoints

Passagem de variáveis de ambiente

Para definir automaticamente variáveis de ambiente para um usuário, inclua-as na URL. Essas variáveis persistirão em todos os endpoints no documento.

Exemplos:

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

Melhor prática

Variáveis de ambiente persistem entre endpoints, enquanto outros tipos de parâmetros (query, path, body, cabeçalho, cookie) são limitados ao endpoint específico na URL. Este método é ideal para compartilhar valores reutilizáveis entre vários endpoints.

Incorporação de valores em URLs de documentação

Comportamento dos parâmetros#

Passagem de valores de parâmetros#

Modo Simples#

Modo Complexo#

Passagem de variáveis de ambiente#

Comportamento dos parâmetros

Passagem de valores de parâmetros

Modo Simples

Modo Complexo

Passagem de variáveis de ambiente