Incorporar Valores em URLs de Documentação

Melhore a colaboração incorporando valores específicos de parâmetros e variáveis diretamente nos URLs de documentação partilhada. Por predefinição, os documentos partilhados contêm apenas especificações da API. Esta funcionalidade permite-lhe partilhar valores pré-preenchidos, facilitando aos utilizadores testar endpoints com configurações específicas.

Comportamento dos Parâmetros

Os valores dos parâmetros passados através do URL comportam-se de forma diferente consoante o respetivo tipo:

Variáveis de Ambiente: Os valores definidos através do URL são aplicados globalmente a todos os endpoints no documento. Persistem ao navegar entre endpoints ou ao abrir novos separadores, permanecendo ativos até serem explicitamente substituídos ou alterados manualmente

Parâmetros do Pedido (Consulta, Caminho, Corpo, Cabeçalho, Cookie): Estes valores estão limitados ao endpoint específico acedido através do URL e não persistem ao navegar para outros endpoints

Passar Valores de Parâmetros

Estão disponíveis dois métodos para incorporar valores de parâmetros: Modo Simples e Modo Complexo. O Modo Simples é mais conciso e não requer codificação de URL, mas não consegue processar caracteres de parênteses retos. O Modo Complexo suporta todos os caracteres, mas requer codificação de URL dos dados dos parâmetros.

Modo Simples

O Modo Simples utiliza 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 Consulta	`query[xxx]=yyy`		Apenas o endpoint atual
Parâmetros de Caminho	`path[xxx]=yyy`		Apenas o endpoint atual
Parâmetros do Corpo	`body[xxx]=yyy`	Para tipos de corpo `form-data` ou `x-www-form-urlencoded`	Apenas o endpoint atual
Parâmetros do Corpo	`body=yyy`	Para outros tipos de corpo (por exemplo, JSON bruto, XML)	Apenas o endpoint atual
Parâmetros de Cabeçalho	`header[xxx]=yyy`		Apenas o endpoint atual
Parâmetros de Cookie	`cookie[xxx]=yyy`		Apenas o endpoint atual
Variáveis de Ambiente	`environment[xxx]=yyy`	Define o valor no ambiente predefinido.	Persiste entre endpoints

Modo Complexo

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

Exemplo de JSON (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"]
    ]
}

Exemplo de URL (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 Consulta	`query`	Um array de pares chave-valor.	Apenas o endpoint atual
Parâmetros de Caminho	`path`	Um array de pares chave-valor.	Apenas o endpoint atual
Parâmetros do Corpo	`body`	Um array de pares chave-valor para `form-data` ou `x-www-form-urlencoded`; uma string para outros tipos de corpo.	Apenas o endpoint atual
Parâmetros de Cabeçalho	`header`	Um array de pares chave-valor.	Apenas o endpoint atual
Parâmetros de Cookie	`cookie`	Um array de pares chave-valor.	Apenas o endpoint atual
Variáveis de Ambiente	`environment`	Um array de pares chave-valor. Define valores no ambiente predefinido.	Persiste entre endpoints

Passar Variáveis de Ambiente

Para definir automaticamente variáveis de ambiente para um utilizador, inclua-as no URL. Estas variáveis irão persistir em todos os endpoints no documento.

Exemplos:

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

Melhor Prática

As variáveis de ambiente persistem entre endpoints, enquanto outros tipos de parâmetros (consulta, caminho, corpo, cabeçalho, cookie) estão limitados ao endpoint específico no URL. Este método é o mais indicado para partilhar valores reutilizáveis entre vários endpoints.

Incorporar Valores em URLs de Documentação

Comportamento dos Parâmetros#

Passar Valores de Parâmetros#

Modo Simples#

Modo Complexo#

Passar Variáveis de Ambiente#

Comportamento dos Parâmetros

Passar Valores de Parâmetros

Modo Simples

Modo Complexo

Passar Variáveis de Ambiente