swagger 请求中的 openapi 自定义参数

Question

在 api 中有一个带有任意数量的近似这种可选参数的路径：

/orders/123/get-payment-link/provider?customerId=123&amount=2000&custom1=custom1&custom2=custom2...

api 描述如下所示：

paths:
  /orders/{orderId}/get-payment-link/{providerName}:
    get:
      operationId: order_get_payment_link
      tags:
        - /orders
      parameters:
        ...
        - name: customerId
          in: query
          required: true
          example: 123
          schema:
            type: string
        - name: amount
          in: query
          required: true
          example: 2000
          schema:
            type: string
        ...

我不明白如何描述自定义类型的任意可选参数，可以是任意数字，可以任意调用？

Answer 1

老实说，我不认为你能做到这一点。我仔细检查了规范，但没有看到自定义名称的方法。

JSON Schema 允许使用诸如 patternProperties 之类的关键字，但不适合参数对象！

在规范 GitHub 上寻找问题我确实找到了 this issue，如果您使用的是 foo[custom1]=a&foo[custom2]=b，这会有所帮助

      - in: query
        name: filter
        required: false
        schema:
          type: object
          additionalProperties: true
          example:
            foo: bar
            inputs.datetime.gte: 242839744
        style: deepObject

        # The example translates to:
        # ?filter[foo]=bar&filter[inputs.datetime.gte]=242839744

至于任意顶级查询参数？不可能。至少在 v3.0 或 v3.1 中没有。