1. Overview

1.概述

In this tutorial, we’ll learn how to work with JSON objects as query parameters using OpenAPI.

在本教程中，我们将学习如何使用OpenAPI处理作为查询参数的JSON对象。

2. Query Parameters in OpenAPI 2

2.OpenAPI 2中的查询参数

OpenAPI 2 doesn’t support objects as query parameters; only primitive values and arrays of primitives are supported.

OpenAPI 2不支持对象作为查询参数；只支持基元值和基元数组。

Because of that, we’ll instead want to define our JSON parameter as a string.

正因为如此，我们要把我们的JSON参数定义为一个字符串。

To see this in action, let’s define a parameter called params as a string, even though we’ll parse it as JSON in our backend:

为了看到这一点，让我们把一个名为params的参数定义为string，尽管我们将在后端把它解析为JSON。

swagger: "2.0"
...
paths:
  /tickets:
    get:
      tags:
      - "tickets"
      summary: "Send an JSON Object as a query param"
      parameters:
      - name: "params"
        in: "path"
        description: "{\"type\":\"foo\",\"color\":\"green\"}"
        required: true
        type: "string"

Thus, instead of:

因此，而不是。

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

we’ll do:

我们会做的。

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

3. Query Params in OpenAPI 3

3.OpenAPI 3中的查询参数

OpenAPI 3 introduces support for objects as query parameters.

OpenAPI 3引入了对作为查询参数的对象的支持。

To specify a JSON parameter, we need to add a content section to our definition that includes the MIME type and schema:

为了指定一个JSON参数，我们需要在我们的定义中添加一个内容部分，包括MIME类型和模式。

openapi: 3.0.1
...
paths:
  /tickets:
    get:
      tags:
      - tickets
      summary: Send an JSON Object as a query param
      parameters:
      - name: params
        in: query
        description: '{"type":"foo","color":"green"}'
        required: true
        schema:
          type: object
          properties:
            type:
              type: "string"
            color:
              type: "string"

Our request can now look like:

我们的请求现在可以看起来像。

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

And, actually, it can still look like:

而且，实际上，它仍然可以看起来像。

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

The first option allows us to use parameter validations, which will let us know if something is wrong before the request is made.

第一个选项允许我们使用参数验证，这将让我们在发出请求之前知道是否有问题。

With the second option, we trade that for greater control on the backend as well as OpenAPI 2 compatibility.

对于第二个选项，我们用它来换取对后端的更大控制权以及OpenAPI 2的兼容性。

4. URL Encoding

4.URL 编码

It’s important to note that, in making this decision to transport request parameters as a JSON object, we’ll want to URL-encode the parameter to ensure safe transport.

需要注意的是，在做出将请求参数作为JSON对象传输的决定时，我们要对参数进行URL编码，以确保安全传输。

So, to send the following URL:

因此，要发送以下网址。

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

We’d actually do:

我们实际上会做。

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

5. Limitations

5.限制条件

Also, let’s keep in mind the limitations of passing a JSON object as a set of query parameters:

另外，让我们牢记将JSON对象作为一组查询参数传递的局限性。

reduced security
limited length of the parameters

For example, the more data we place in a query parameter, the more appears in server logs and the higher the potential for sensitive data exposure.

例如，我们在查询参数中放置的数据越多，服务器日志中出现的数据就越多，敏感数据暴露的可能性就越大。

Also, a single query parameter can be no longer than 2048 characters. Certainly, we can all imagine scenarios where our JSON objects are larger than that. Practically speaking, a URL encoding of our JSON string will actually limit us to about 1000 characters for our payload.

另外，一个查询参数的长度不能超过2048个字符。当然，我们都可以想象我们的JSON对象大于这个长度的情况。实际上，我们的JSON字符串的URL编码实际上将我们的有效载荷限制在1000个字符左右。

One workaround is to send larger JSON Objects in the body. In this way, we fix both the security issue and the JSON length limitation.

一个解决方法是在正文中发送较大的JSON对象。通过这种方式，我们既解决了安全问题，又解决了JSON长度的限制。

Actually, GET or POST both support this. One reason to send a body over GET is to maintain the RESTful semantics of our API.

实际上，GET或POST都支持这一点。通过GET发送主体的一个原因是为了保持我们的API的RESTful语义。

Of course, it’s a bit unusual and not universally supported. For instance, some JavaScript HTTP libraries don’t allow GET requests to have a request body.

当然，这有点不寻常，也不被普遍支持。例如，一些JavaScript HTTP库不允许GET请求有一个请求体。

In short, this choice is a trade-off between semantics and universal compatibility.

简而言之，这种选择是在语义和普遍兼容性之间进行权衡。

6. Conclusion

6.结语

To sum up, in this article we learned how to specify JSON objects as query parameters using OpenAPI. Then, we observed some of the implications on the backend.

总而言之，在这篇文章中我们学习了如何使用OpenAPI指定JSON对象作为查询参数。然后，我们观察了后台的一些影响。

The complete OpenAPI definitions for these examples are available over on GitHub.

这些示例的完整OpenAPI定义可在GitHub上获得。