1. 概述

在本教程中，我們將學習如何使用 JSON 對象作為查詢參數，並使用 OpenAPI 進行操作。

2. OpenAPI 2 中的查詢參數

OpenAPI 2 不支持對象作為查詢參數；僅支持原始值和原始值的數組。

因此，我們應該將 JSON 參數定義為 字符串。

要查看這一點，讓我們定義一個名為 params 的參數為 字符串，即使我們將在後端將其解析為 JSON：

swagger: "2.0"
...
paths:
  /tickets:
    get:
      tags:
      - "tickets"
      summary: "將 JSON 對象作為查詢參數發送"
      parameters:
      - name: "params"
        in: "path"
        description: "{\"type\":\"foo\",\"color\":\"green\"}"
        required: true
        type: "string"

因此，而不是：

GET http://localhost:8080/api/tickets?type=foo&color=green

我們將執行：

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. OpenAPI 3 中的 Query Params

OpenAPI 3 引入了對象作為查詢參數的支持。

為了指定 JSON 參數，我們需要向定義中添加 content 部分，其中包含 MIME 類型和模式：

openapi: 3.0.1
...
paths:
  /tickets:
    get:
      tags:
      - tickets
      summary: 作為查詢參數發送 JSON 對象
      parameters:
      - name: params
        in: query
        description: '{"type":"foo","color":"green"}'
        required: true
        schema:
          type: object
          properties:
            type:
              type: "string"
            color:
              type: "string"

我們的請求現在可以看起來像:

GET http://localhost:8080/api/tickets?params[type]=foo&params[color]=green

而且，實際上，它仍然可以看起來像:

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

第一個選項允許我們使用參數驗證，這將在請求發出之前通知我們是否有問題。

第二個選項，我們以對後端以及 OpenAPI 2 兼容性更大的控制權來換取它。

4. URL 編碼

需要注意的是，我們決定將請求參數作為 JSON 對象傳輸時，需要對參數進行 URL 編碼，以確保安全傳輸。

因此，要發送以下 URL：

GET /tickets?params={"type":"foo","color":"green"}

實際上我們會執行:

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. 限制

此外，請務必記住將 JSON 對象作為查詢參數傳遞的限制:

• 降低安全性
• 參數長度有限制

例如,我們放置在查詢參數中的數據越多, 出現的服務器日誌就越多,從而增加了敏感數據泄露的潛在風險。

此外，單個查詢參數不能超過 2048 個字符。 毫無疑問，我們都能想象到我們的 JSON 對象大於這個值的場景。 實際上，對 JSON 字符串的 URL 編碼會將我們的有效負載限制在約 1000 個字符左右。

一種解決方法是將較大的 JSON 對象發送到請求體中。 這樣，我們就可以同時解決安全問題和 JSON 長度限制。

事實上,GET 或 POST 都支持這種方法。 使用 GET 發送請求體的原因是為了保持我們 API 的 RESTful 語義。

當然，這有點不尋常，並且並非所有庫都支持它。 例如，某些 JavaScript HTTP 庫不允許 GET 請求具有請求體。

總之，這是一個語義和通用兼容性之間的權衡。

6. 結論

總而言之，在本文中，我們學習瞭如何使用 OpenAPI 將 JSON 對象指定為查詢參數。然後，我們觀察了這些對後端的影響。