如何在 OpenAPI 3.0 中定义带有两个可选参数的路径？

Question

我在 SwaggerHub 注册并使用 OpenAPI 3.0 创建了一个新的 API。在我的 API 中，/tasks 路径有 2 个非必需参数，但我无法将它们设置为不需要 - 编辑器显示 "Not allowed Values" 错误。

这是我的 API 定义：

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number to be fetched. If missed default 1.
          required: true
          schema:
            type: integer
        - name: order_by
          in: path
          description: The order_by  be fetched. 
          required: false  // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
        - name: filter
          in: path
          description: The filter for title field. 
          required: false // ERROR : should be equal to one of the allowed values allowedValues: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid tasks supplied
        '404':
          description: tasks were not found

但是如果我删除 required 属性，我会得到 2 个错误：

should have required property 'required'
missingProperty: required

什么是有效语法？

Answer 1

这些参数应该是路径参数还是查询参数？

路径参数 (in: path) 是端点路径的一部分，因此必须在路径模板中用 {...} 表示：

paths:
  /tasks/{page}/{order_by}/{filter}:

路径参数始终是必需的，即它们必须具有 required: true.

查询参数在查询字符串中发送，例如/tasks?page=...&order_by=...。要使用查询参数，请将参数位置更改为 in: query.

更多信息：Describing Parameters

如何在 OpenAPI 3.0 中定义带有两个可选参数的路径？

How to define a path with two optional parameters in OpenAPI 3.0?

openapi

swagger-editor