如何在OpenAPI中实现参数类型随另一参数值动态变化？

OpenAPI 3.0及以上版本完全支持这种参数间的类型依赖约束，下面提供两种合规的实现方式：

方法1：使用oneOf结构 #

通过定义两组互斥的参数组合，强制请求必须匹配其中一组规则：

openapi: 3.0.3
paths:
  /mypath:
    get:
      parameters:
        - name: mode
          in: query
          required: true
          schema:
            type: string
            enum: [modeA, modeB]
        - name: input
          in: query
          required: true
          schema:
            type: [integer, string]  # 声明支持两种基础类型
      responses:
        '200':
          description: OK
      # 核心约束：二选一的参数组合
      oneOf:
        - parameters:
            - name: mode
              in: query
              schema:
                enum: [modeA]
            - name: input
              in: query
              schema:
                type: integer
        - parameters:
            - name: mode
              in: query
              schema:
                enum: [modeB]
            - name: input
              in: query
              schema:
                type: string

方法2：使用if/then/else结构 #

通过$request.query.<参数名>语法引用Query参数，实现条件分支约束：

openapi: 3.0.3
paths:
  /mypath:
    get:
      parameters:
        - name: mode
          in: query
          required: true
          schema:
            type: string
            enum: [modeA, modeB]
        - name: input
          in: query
          required: true
          schema:
            type: [integer, string]
      responses:
        '200':
          description: OK
      # 核心条件约束
      if:
        properties:
          query:
            properties:
              mode:
                const: modeA
      then:
        properties:
          query:
            properties:
              input:
                type: integer
      else:
        properties:
          query:
            properties:
              mode:
                const: modeB
              input:
                type: string

注意事项 #

• 上述两种方案均要求OpenAPI版本≥3.0，3.1版本对条件约束的语法支持更灵活。
• 确保mode参数的enum仅包含modeA和modeB，避免无效值干扰约束逻辑。
• 部分API文档工具（如Swagger UI 3.x+）能正确解析并展示这种参数依赖关系，但老旧工具可能不支持，需提前验证兼容性。

内容的提问来源于stack exchange，提问作者S-Man