You need to enable JavaScript to run this app. 如何在OpenAPI规范中实现不同层级Schema示例的覆盖与合并
优惠活动
大模型
产品
解决方案
定价
更多

如何在OpenAPI规范中实现不同层级Schema示例的覆盖与合并

问题原因

OpenAPI 3.x 规范明确约定了字段同级显式声明的example优先级远高于内部嵌套schema的example。你在config字段直接定义了完整的示例对象{ spec: { team: 76ers, names: [ 1, 2 ] } },所以Swagger等渲染工具会直接取用这个完整对象,不会自动合并内部Names schema的预设示例,这是规范约定的正常逻辑,并非工具故障。

解决方案

目前OpenAPI规范没有提供自动跨层级合并示例的能力,要实现team为76ers、names为[Ben, Joel]的组合示例,可以选择以下两种方案:

方案1:拆分示例到对应子字段

不要直接给config字段写完整示例,把自定义示例下放到对应的子字段层级,未自定义的字段会自动继承下层schema的示例:

PlayerWrapper:
  type: object
  properties:
    display_name:
      type: string
      example: 76ers
    config:
      description: |
        播放器的配置信息。
      allOf:
        - $ref: '#/components/schemas/Player'
      # 仅定义自定义的子字段示例,names示例自动继承Names schema
      properties:
        spec:
          properties:
            team:
              example: 76ers

方案2:直接声明完整的目标示例

如果不想调整schema结构,直接修改config字段的example为你想要的最终结果即可:

config:
  description: |
    播放器的配置信息。
  # 直接写组合后的完整示例
  example: { spec: { team: 76ers, names: [ Ben, Joel ] } }
  allOf:
    - $ref: '#/components/schemas/Player'

内容的提问来源于stack exchange,提问作者Alex Ivanov

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.15 03:45:01