Nhúng giá trị vào URL tài liệu

Tăng cường khả năng cộng tác bằng cách nhúng trực tiếp các giá trị tham số và biến cụ thể vào URL tài liệu được chia sẻ. Theo mặc định, tài liệu được chia sẻ chỉ chứa đặc tả API. Tính năng này cho phép bạn chia sẻ các giá trị đã được điền sẵn, giúp người dùng dễ dàng kiểm thử endpoint với các cấu hình cụ thể hơn.

Hành vi của tham số

Các giá trị tham số được truyền qua URL sẽ có hành vi khác nhau tùy theo loại của chúng:

Biến môi trường: Các giá trị được thiết lập thông qua URL sẽ được áp dụng toàn cục trên tất cả endpoint trong tài liệu. Chúng vẫn được duy trì khi điều hướng giữa các endpoint hoặc mở tab mới, và tiếp tục có hiệu lực cho đến khi được ghi đè rõ ràng hoặc thay đổi thủ công.

Tham số yêu cầu (Query, Path, Body, Header, Cookie): Các giá trị này chỉ có phạm vi trong endpoint cụ thể được truy cập qua URL và không được duy trì khi điều hướng sang các endpoint khác.

Truyền giá trị tham số

Có hai phương pháp để nhúng giá trị tham số: Chế độ đơn giản và Chế độ phức tạp. Chế độ đơn giản ngắn gọn hơn và không yêu cầu mã hóa URL, nhưng không thể xử lý ký tự dấu ngoặc vuông. Chế độ phức tạp hỗ trợ tất cả ký tự nhưng yêu cầu mã hóa URL dữ liệu tham số.

Chế độ đơn giản

Chế độ đơn giản sử dụng định dạng parameterType[parameterName]=value.

Ví dụ:

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

Loại tham số	Định dạng giá trị tham số	Mô tả	Hành vi
Tham số Query	`query[xxx]=yyy`		Chỉ endpoint hiện tại
Tham số Path	`path[xxx]=yyy`		Chỉ endpoint hiện tại
Tham số Body	`body[xxx]=yyy`	Dành cho các loại body `form-data` hoặc `x-www-form-urlencoded`	Chỉ endpoint hiện tại
Tham số Body	`body=yyy`	Dành cho các loại body khác (ví dụ: raw JSON, XML)	Chỉ endpoint hiện tại
Tham số Header	`header[xxx]=yyy`		Chỉ endpoint hiện tại
Tham số Cookie	`cookie[xxx]=yyy`		Chỉ endpoint hiện tại
Biến môi trường	`environment[xxx]=yyy`	Thiết lập giá trị trong môi trường mặc định.	Được duy trì trên các endpoint

Chế độ phức tạp

Chế độ phức tạp truyền một đối tượng JSON đã được mã hóa URL làm giá trị của tham số params. Đối tượng JSON này phải được mã hóa bằng encodeURIComponent. Trong JavaScript, có thể thực hiện bằng: encodeURIComponent(JSON.stringify({"query":["id",1]})).

Ví dụ JSON (trước khi mã hóa):

{
    "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 ví dụ (sau khi mã hóa):

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

Loại tham số	Giá trị tham số	Mô tả	Hành vi
Tham số Query	`query`	Một mảng các cặp khóa-giá trị.	Chỉ endpoint hiện tại
Tham số Path	`path`	Một mảng các cặp khóa-giá trị.	Chỉ endpoint hiện tại
Tham số Body	`body`	Một mảng các cặp khóa-giá trị cho `form-data` hoặc `x-www-form-urlencoded`; một chuỗi cho các loại body khác.	Chỉ endpoint hiện tại
Tham số Header	`header`	Một mảng các cặp khóa-giá trị.	Chỉ endpoint hiện tại
Tham số Cookie	`cookie`	Một mảng các cặp khóa-giá trị.	Chỉ endpoint hiện tại
Biến môi trường	`environment`	Một mảng các cặp khóa-giá trị. Thiết lập giá trị trong môi trường mặc định.	Được duy trì trên các endpoint

Truyền biến môi trường

Để tự động thiết lập biến môi trường cho người dùng, hãy đưa chúng vào URL. Các biến này sẽ được duy trì trên tất cả endpoint trong tài liệu.

Ví dụ:

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

Phương pháp hay nhất

Biến môi trường được duy trì trên các endpoint, trong khi các loại tham số khác (query, path, body, header, cookie) chỉ có phạm vi trong endpoint cụ thể trong URL. Phương pháp này phù hợp nhất để chia sẻ các giá trị có thể tái sử dụng trên nhiều endpoint.

Nhúng giá trị vào URL tài liệu

Hành vi của tham số#

Truyền giá trị tham số#

Chế độ đơn giản#