문서 URL에 값 임베드하기

공유 문서 URL 내에 특정 매개변수 및 변수 값을 직접 임베드하여 협업을 강화하십시오. 기본적으로 공유 문서에는 API 사양만 포함됩니다. 이 기능을 사용하면 미리 채워진 값을 공유할 수 있으므로, 사용자가 특정 구성으로 엔드포인트를 더 쉽게 테스트할 수 있습니다.

매개변수 동작

URL을 통해 전달된 매개변수 값은 유형에 따라 다르게 동작합니다.

환경 변수: URL을 통해 설정된 값은 문서 내 모든 엔드포인트에 전역적으로 적용됩니다. 엔드포인트 간 이동하거나 새 탭을 열 때도 유지되며, 명시적으로 재정의하거나 수동으로 변경할 때까지 활성 상태로 남아 있습니다.

요청 매개변수(Query, Path, Body, Header, Cookie): 이러한 값은 URL을 통해 접근한 특정 엔드포인트로 범위가 제한되며, 다른 엔드포인트로 이동할 때 유지되지 않습니다.

매개변수 값 전달하기

매개변수 값을 임베드하는 두 가지 방법인 Simple Mode와 Complex Mode를 사용할 수 있습니다. Simple Mode는 더 간결하고 URL 인코딩이 필요하지 않지만, 대괄호 문자를 처리할 수 없습니다. Complex Mode는 모든 문자를 지원하지만 매개변수 데이터의 URL 인코딩이 필요합니다.

Simple Mode

Simple Mode는 parameterType[parameterName]=value 형식을 사용합니다.

예시:

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

매개변수 유형	매개변수 값 형식	설명	동작
Query Parameters	`query[xxx]=yyy`		현재 엔드포인트에만 적용
Path Parameters	`path[xxx]=yyy`		현재 엔드포인트에만 적용
Body Parameters	`body[xxx]=yyy`	`form-data` 또는 `x-www-form-urlencoded` 본문 유형용	현재 엔드포인트에만 적용
Body Parameters	`body=yyy`	기타 본문 유형용(예: raw JSON, XML)	현재 엔드포인트에만 적용
Header Parameters	`header[xxx]=yyy`		현재 엔드포인트에만 적용
Cookie Parameters	`cookie[xxx]=yyy`		현재 엔드포인트에만 적용
Environment Variables	`environment[xxx]=yyy`	기본 환경에 값을 설정합니다.	엔드포인트 간 유지

Complex Mode

Complex Mode는 URL 인코딩된 JSON 객체를 params 매개변수의 값으로 전달합니다. 이 JSON 객체는 encodeURIComponent를 사용하여 인코딩해야 합니다. JavaScript에서는 다음과 같이 수행할 수 있습니다. encodeURIComponent(JSON.stringify({"query":["id",1]})).

예시 JSON(인코딩 전):

{
    "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(인코딩 후):

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

매개변수 유형	매개변수 값	설명	동작
Query Parameters	`query`	키-값 쌍의 배열입니다.	현재 엔드포인트에만 적용
Path Parameters	`path`	키-값 쌍의 배열입니다.	현재 엔드포인트에만 적용
Body Parameters	`body`	`form-data` 또는 `x-www-form-urlencoded`용 키-값 쌍의 배열이며, 기타 본문 유형의 경우 문자열입니다.	현재 엔드포인트에만 적용
Header Parameters	`header`	키-값 쌍의 배열입니다.	현재 엔드포인트에만 적용
Cookie Parameters	`cookie`	키-값 쌍의 배열입니다.	현재 엔드포인트에만 적용
Environment Variables	`environment`	키-값 쌍의 배열입니다. 기본 환경에 값을 설정합니다.	엔드포인트 간 유지

환경 변수 전달하기

사용자에게 환경 변수를 자동으로 설정하려면 URL에 해당 변수를 포함하십시오. 이러한 변수는 문서 내 모든 엔드포인트에서 유지됩니다.

예시:

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

모범 사례

환경 변수는 엔드포인트 간 유지되는 반면, 기타 매개변수 유형(query, path, body, header, cookie)은 URL의 특정 엔드포인트로 범위가 제한됩니다. 이 방법은 여러 엔드포인트에서 재사용 가능한 값을 공유하는 데 가장 적합합니다.

문서 URL에 값 임베드하기

매개변수 동작#

매개변수 값 전달하기#

Simple Mode#

Complex Mode#

환경 변수 전달하기#

매개변수 동작

매개변수 값 전달하기

Simple Mode

Complex Mode

환경 변수 전달하기