为何Swagger schema中properties下的example字段生成文档时不显示？

基础规范结构问题 #

你当前编写的YAML片段存在两处不符合OpenAPI规范结构要求的问题：

• 定义的PlayerConfig、sports_config没有挂载到规范要求的components/schemas专属路径下，脱离该路径的模型节点不会被文档工具识别抓取。
• sports_config节点没有定义自身的归属层级与基础类型，属于孤立配置，无法进入文档渲染管线。

模型引用的合法性说明 #

你尝试通过$ref引用已有模型作为oneOf分支类型的写法，是OpenAPI 3.0+规范明确支持的合法用法，完全可以用现有模型作为多态类型的分支引用。搭配oneOf配置discriminator的写法也符合多态模型的定义规范，只要每个oneOf分支模型都包含discriminator指定的kind字段，即可被规范正确识别。

Example渲染差异的本质原因 #

你观察到的「parameters节点下的example可以正常渲染、properties节点下的example不显示」的差异，并非配置错误导致，是不同文档渲染工具的内置策略差异：

• OpenAPI规范本身明确支持在Schema的属性层级配置example，作为对应字段的示例值，你对照官方文档确认的配置逻辑完全符合规范要求。
• 你复现的Redoc工具默认渲染逻辑为：优先展示Schema顶层配置的聚合example，不会逐字段展开渲染属性上单独配置的example。这是工具本身的渲染选择，不是配置失效。
• 你看到parameters节点下的example可以正常显示，是因为参数板块的渲染逻辑本身就是逐参数展示对应配置的example，和Schema板块的渲染逻辑不统一。

适配渲染的调整方案 #

如果需要让配置的example在Redoc生成的文档中正常展示，可以参考两个方向调整：

• 不在单个属性下单独配置example，转而在Schema的顶层节点配置聚合的整体示例，例如给PlayerConfig根节点添加example: {kind: "PlayerConfig", player_id: "foo"}，这种写法是Redoc会优先识别渲染的。
• 如果需要逐字段展示对应示例，可以切换支持逐属性渲染example的OpenAPI文档工具，新版Swagger UI就会在每个属性的说明卡片旁直接展示对应的字段级example。

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