Swagger 架构属性被忽略 - 为什么？答案

【问题标题】：Swagger schema properties ignored - why?Swagger 架构属性被忽略 - 为什么？
【发布时间】：2021-04-23 12:48:21
【问题描述】：

我正在尝试构建一个简单的 Swagger 模型：

PlayerConfig:
  type: object
  required:
    - kind
    - player_id
  properties:
    kind:
      type: string
      example: PlayerConfig
    player_id:
      type: string
      example: "foo"
      description: "bar"

sports_config:
  oneOf:
    - $ref: '#/components/schemas/PlayerConfig'
  discriminator:
    propertyName: kind

由于某种原因，生成的 HTML 没有显示 player_id 的 example 字段。这让我觉得我做的不对。s

所以问题是，使用模型作为类型实际上是否可以像我试图做的那样完成。如果example 字段的父字段是parameters: 而不是properties:，则该字段会被渲染。

更新：我阅读了 https://swagger.io/docs/specification/adding-examples/ 上的 Object and Property Examples 部分，看来我的代码 sn-p 应该可以工作。

更新 #2：我实际上下载了 redoc-cli（这是 OpenAPI 的 CLI 工具 -> html 包）并从 Swagger Editor 中获取了一个示例规范，该规范在 properties 下具有 example 字段，它模仿了我的问题和它看起来像预期的那样（见我附上的截图）：

【问题讨论】：

您使用的是什么文档工具？
文档工具是什么意思？
更新：我正在使用 ReDoc：github.com/Redocly/redoc

标签： swagger openapi swagger-2.0 redoc

【解决方案1】：

如果字符串值包含空格（或其他一些特殊字符），则应将其括在引号中。所以该行应该是

  example: "LeBron James"

【讨论】：

感谢您的建议！已经试过了，可惜还是不行。
@AlexIvanov 也许下一行的单引号有问题？您是否尝试将描述用引号括起来？
更新了问题。