招摇的同一模型的不同示例

Question

我正在尝试在我的 Swagger 文件的请求部分中创建一个示例。在下面的（高度简化的）片段中，我的请求描述了患者和临床医生之间的关系。这两个实体都使用相同的 Identifier 模型。

但是，我似乎无法弄清楚如何在 patientIdentifier 和 clinicianIdentifier 中传递不同的示例数据，同时仍然使用常见的 Identifier 模型。我发布的代码片段在语法上是正确的，但显然在示例数据中，两个标识符的数据是相同的，这远非理想。

我知道我可以从 Identifer 模型中提取字段并将它们复制到 patientIdentifier 和 clinicianIdentfier，在这种情况下不需要太多努力，但我想要想知道是否有更优雅的方法来实现这一点。

Relationship:
  properties:
    patientIdentifier:
      $ref: '#/definitions/Identifier'
    clinicianIdentifier:
      $ref: '#/definitions/Identifier'

Identifier:
  type: object
  properties:
    id:
      type: string
      example: "Jane Doe"
    group:
      type: string
      example: "WD7"

如果有人能根据文档或示例为我指明正确的方向，我将不胜感激。

谢谢！

Answer 1

您需要为 Relationship 提供架构级示例。架构级示例优先于属性级示例。

Relationship:
  type: object
  properties:
    patientIdentifier:
      $ref: '#/definitions/Identifier'
    clinicianIdentifier:
      $ref: '#/definitions/Identifier'
  example:
    patientIdentifier:
      id: Jane Doe
      group: WD7
    clinicianIdentifier:
      id: Bob Smith
      group: ABCDE

请注意，patientIdentifier 和 clinicianIdentifier 的属性级示例将不起作用，因为在使用 $ref 时，$ref 的任何兄弟姐妹被忽略。

# This won't work - examples will be ignored

Relationship:
  type: object
  properties:
    patientIdentifier:

      $ref: '#/definitions/Identifier'
      example:
        id: Jane Doe
        group: WD7

    clinicianIdentifier:

      $ref: '#/definitions/Identifier'
      example:
        id: Bob Smith
        group: ABCDE

招摇的同一模型的不同示例

Different examples for same model in swagger

swagger

api-design

swagger-editor