大胆地定义API：在参数中使用JSON的GET调用

Question

我正在尝试创建一个适当的REST API，并使用Swagger（2.0）对其进行记录。

因此，我有一个作为查询的API调用，即它不做任何更改且不创建任何东西（幂等且安全）。但它需要传入一个复杂的JSON参数（项目列表，2或3组地址等）。因此，我正在使用带有URL编码JSON的参数进行GET。这似乎是正确的方法。

我经常看到这样的API，因此他们将其作为POST进行，但这是对POST动词的错误使用。

我看到很多的swagger API都可以做到这一点...

我不知道是否有一种方法可以使用JSON参数与Swagger一起使用适当的rest API。您当然可以将参数定义为字符串，然后将编码后的JSON传递给该字符串，但是swagger工具无法理解它是否具有架构/定义。

昂首阔步是否无法正确记录此类呼叫？

Answer 1

OpenAPI 2.0 (Swagger 2.0)

OpenAPI 2.0 不支持查询字符串中的对象，它只支持原始值和原始数组。您最多可以将参数定义为type: string，添加example一个 JSON 值，并用于description记录 JSON 对象结构。

swagger: '2.0'
...
paths:
  /something:
    get:
      parameters:
        - in: query
          name: params
          required: true
          description: A JSON object with the `id` and `name` properties
          type: string
          example: '{"id":4,"name":"foo"}'

开放API 3.x

查询字符串中的 JSON 可以使用 OpenAPI 3.x 进行描述。在 OAS 3 中，查询参数可以是基元、数组和对象，您可以指定这些参数应该如何序列化——扁平key=value成对、编码为 JSON 字符串等等。

对于包含 JSON 字符串的查询参数，使用content关键字schema为 JSON 数据定义一个：

openapi: 3.0.1
...

paths:
  /something:
    get:
      parameters:
        - in: query
          name: params
          required: true

          # Parameter is an object that should be serialized as JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

这对应于以下 GET 请求（在 URL 编码之前）：

GET /something?params={"id":4,"name":"foo"}

或在 URL 编码后：

GET /something?params=%7B%22id%3A4%2C%22name%22%3A%22foo%22%7D

Swagger UI 用户注意事项：Swagger UI 3.23.8+和Swagger Editor 3.6.34+支持
参数。content

早期版本的 UI/编辑器的解决方法：
将参数定义为 justtype: string并添加一个exampleJSON 数据。您无法描述查询字符串的 JSON 模式，但“尝试一下”会起作用。

GET /something?params={"id":4,"name":"foo"}