在 OpenAPI 3.0 中使用组件模式作为查询参数是否正确？答案

【问题标题】：Is it correct to use schemas of components for query parameter in OpenAPI 3.0?在 OpenAPI 3.0 中使用组件模式作为查询参数是否正确？
【发布时间】：2021-04-15 02:58:01
【问题描述】：

OpenAPI“组件”部分具有“模式”和“参数”。

https://swagger.io/docs/specification/components/#structure

看起来我可以用任何一种方式编写查询参数。
但是使用“模式”部分编写查询参数是否正确？

使用模式部分似乎很方便，因为它可以重复用于响应等。

paths:
  /user:
    get:
      summary: Get User
      operationId: get-user
      description: ''
      parameters:
        - schema:
            $ref: '#/components/schemas/User'
          in: query
          name: schemas_user
          required: true
        - $ref: '#/components/parameters/QueryUser'
      responses:
        '200':
          description: OK
components:
  schemas:
    User:
      title: User
      type: string
      description: user in model
  parameters:
    QueryUser:
      name: query_user
      in: query
      required: true
      schema:
        type: string
      description: user in query

'schemas' 很有表现力，也可以表示对象。

但是，对象不能用作查询字符串。

OpenAPI 是否建议对查询字符串使用模式？

【问题讨论】：

标签： swagger openapi

【解决方案1】：

是的，引用#components/schemas 中的架构看起来不错。请参阅下面的快照，确认相同。 PS：您可以尝试将 Swagger JSON 粘贴到 editor.swagger.io

【讨论】：

感谢您的回复。我知道我可以使用模式，但我想知道是否应该使用它。 schemas 非常有表现力，也可以表示对象。但是，对象不能用作查询字符串。 OpenAPI 是否建议对查询字符串使用模式？
嘿，考虑到您的疑问，IMO OpenAPI 是如此强大，允许您从 /components/schemas 引用它。但是将对象表示为查询参数在一般的 REST 世界本身中没有多大意义，因此您可能会考虑在请求正文中容纳对象。因此，通过 $ref 或内联定义更好地表示普通数据类型的数组或仅代表查询参数的普通数据类型。