Openapi:共享参数和组件描述

Question

我在openapi 3.0.0中有一个web服务描述(升级不是问题)。

此webservice将接受多个POST参数，并将返回响应中的所有这些参数。在这个意义上，我想找到一种分享字段描述的方法。

根据我的不足，组件也可以作为响应元素、参数作为模式共享，但格式不同(包括query之类的字段)，但是可以在同一位置共享它们，将它们表示为来自响应和服务参数的两个元素。

我所见过的样本是可能的：

        - name: filter
          in: query
          schema:
            type: object
            allOf:
              - $ref: '#/components/schemas/SomeComponent'

在这里，我了解到SomeComponent中的每个字段都将嵌套在过滤器下面，我希望将它们作为一阶参数。

编辑--一个来自开放API解析器的屏幕截图，显示了这个嵌套：

​

​

Answer 1

在这里，我了解到SomeComponent中的每个字段都将嵌套在过滤器下面，我希望将它们作为一阶参数。

在OpenAPI中，查询参数的串行化方法取决于参数的style和explode属性。默认方法是style: form + explode: true，这意味着对象被分解成单独的key=value对--就像您想要的那样。在这种情况下，参数名(在您的示例中是filter)可以是任意的，因为它实际上并不出现在请求URL中。

换句话说，这个定义

      parameters:
        - name: filter
          in: query
          schema:
            $ref: '#/components/schemas/SomeComponent'

components:
  schemas:
    SomeComponent:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: string

对应于

...?foo=value1&bar=value2

尽管Swagger中的“参数”部分将其显示为单个对象类型的参数，但实际的使用单独的key=value参数。

​

​