取决于 URL 路径参数的条件 JSON 模式

Question

我正在尝试编写一个开放的api文档，涉及路径中带有参数的PUT请求，例如PUT /settings/{settingId}

我希望 JSON 有效负载尽可能简约，如下所示： { “价值”：“某事” }

手头的设置（用其设置 ID 标识）必须遵循各种类型、模式或正则表达式，对此我想使用 JSON 模式。例如，如果settingId = eth_enable，我希望该值为布尔值。

我是该领域的初学者，但感觉我的问题的答案还没有在互联网上，这就是为什么我现在在这里问（在询问 ChatGPT 之后，他引导我走上了错误的道路大约周😅）。我尝试使用 JSON 模式实现的操作是否可行，或者路径参数对于 JSON 模式无法使用？

提前感谢您的任何和所有提示！

我在互联网上搜索答案已经有一段时间了，但似乎我找到的所有实现都是基于属性的 JSON 模式，而不是基于路径参数。

Answer 1

描述不同的有效负载是可能的，但要传达哪个有效负载可以工作并不容易，而且无法根据路径参数值仅定义一个模式。您必须定义这两个模式。 区分它们的唯一方法是使用架构中的标题属性。

openapi: 3.1.0
info:
  title: thing
  version: 1.0.0
paths:
  '/xxxx/{some_value}':
    put:
      description: my endpoint
      parameters:
      - name: some_value
        in: path
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/my_put_request'
      responses:
        '200':
          $ref: '#/components/responses/200'
components:
  responses:
    '200':
      description: thing
      content:
        'application/json':
          schema:
            properties:
              value: 
                type: string
          examples:
            eth_enabled:
              value: { value: true }
            eth_disabled:
              value: { value: something }
  schemas:
    schema-one:
      title: schema_one
      type: object
      properties:
        value:
          type: boolean
    schema-two:
      title: schema_two
      type: object
      properties:
        value:
          type: string
  requestBodies:
    my_put_request:
      description: thing
      content:
        'application/json':
          schema:
              anyOf:
              - $ref: '#/components/schemas/schema-one'
              - $ref: '#/components/schemas/schema-two'
      required: true