如何在OpenAPI 3.x中基于可选查询参数文档化不同响应？

方案1：参数组合+明确的响应示例（最推荐，无需改动API） #

直接在同一个/order端点下，把所有查询参数的组合逻辑写清楚，同时给每个组合对应单独的响应示例，让开发者一眼就能对应上参数和返回结构。

具体写法示例：

paths:
  /order:
    get:
      summary: 获取订单信息
      parameters:
        - name: expand
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: 是否展开关联信息
        - name: include
          in: query
          required: false
          schema:
            type: string
            enum: [feature]
          description: 额外包含的字段组，仅在expand=true时生效
      responses:
        '200':
          description: 成功返回订单信息，结构随参数组合变化
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderBasic'
                  - $ref: '#/components/schemas/OrderExpanded'
                  - $ref: '#/components/schemas/OrderExpandedWithFeature'
              examples:
                expand=false:
                  summary: 不展开关联信息的响应
                  value:
                    id: "123"
                    number: "ORD-2024-001"
                    status: "paid"
                expand=true:
                  summary: 展开关联信息的响应
                  value:
                    id: "123"
                    number: "ORD-2024-001"
                    status: "paid"
                    customer:
                      id: "456"
                      name: "张三"
                expand=true&include=feature:
                  summary: 展开关联并包含feature的响应
                  value:
                    id: "123"
                    number: "ORD-2024-001"
                    status: "paid"
                    customer:
                      id: "456"
                      name: "张三"
                    features:
                      - code: "FREE_SHIP"
                        name: "免费配送"

components:
  schemas:
    OrderBasic:
      type: object
      properties:
        id: {type: string}
        number: {type: string}
        status: {type: string}
    OrderExpanded:
      allOf:
        - $ref: '#/components/schemas/OrderBasic'
        - type: object
          properties:
            customer:
              type: object
              properties:
                id: {type: string}
                name: {type: string}
    OrderExpandedWithFeature:
      allOf:
        - $ref: '#/components/schemas/OrderExpanded'
        - type: object
          properties:
            features:
              type: array
              items:
                type: object
                properties:
                  code: {type: string}
                  name: {type: string}

这种方式的核心是用examples把每个参数组合的响应具象化，同时用oneOf关联对应的Schema，开发者既能看到结构化的Schema定义，也能直接看示例对应参数组合，非常直观。

方案2：拆分端点（如果API允许调整） #

如果可以对现有API做微小调整，把不同参数组合拆成语义更明确的端点，比如：

• /order 对应 expand=false
• /order/expanded 对应 expand=true
• /order/expanded?include=feature 保留原参数逻辑

这样每个端点的响应结构单一，文档化会更简单，开发者也不用记忆参数组合的对应关系。但这个方案的前提是你有权限修改API路由。

方案3：用参数依赖+响应描述绑定 #

在参数的description里明确标注依赖关系（比如include仅在expand=true时生效），然后在响应的description里详细说明每个参数组合对应的Schema：

responses:
  '200':
    description: |
      响应结构说明：
      - 当expand=false时，返回`OrderBasic`结构
      - 当expand=true且未传include时，返回`OrderExpanded`结构
      - 当expand=true且include=feature时，返回`OrderExpandedWithFeature`结构
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/OrderBasic'
            - $ref: '#/components/schemas/OrderExpanded'
            - $ref: '#/components/schemas/OrderExpandedWithFeature'

这种方案适合不想加太多示例的场景，靠文字说明把参数和Schema绑定起来。

内容的提问来源于stack exchange，提问作者Aks