如何在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
相关产品推荐
相关产品推荐

