如何在招摇中重用另一个定义中的示例？

Posted 2023-02-19

【中文标题】如何在招摇中重用另一个定义中的示例？

【英文标题】：How to reuse example from another definition in swagger?

【发布时间】：2016-05-06 12:08:14

【问题描述】：

我有一个 report 对象的定义。我有另一个 reports 对象的定义，它有一个 report 对象数组（通过 $ref）。

在 report 定义中，我定义了一个示例，该示例在 swagger UI 中运行良好。

在 reports 定义中，我希望它使用 report 定义中的示例。

我该怎么做？我已经使用 $ref 尝试了几件事，我得到的最接近的是我在以下 YAML 中所拥有的......

definitions:
  report:
    type: object
    properties:
      ID:
        type: number
        format: int
        description: "DB record ID of the report."
        readOnly: true
      ErrorContent:
        type: string
        description: "The actual problem or error infomation for this report. This can be exception stack, etc."
        readOnly: true
      UserComments:
        type: string
        description: "Any user comments collected by the app and submitted with the report."
        readOnly: true
      ReportedBy:
        type: string
        description: "The person using the app when it triggered the error this report is for."
        readOnly: true
      ReportedDateTime:
        type: string
        description: "The date/time the report was submitted."
        readOnly: true
    required:
      - ID
      - ErrorContent
      - ErrorType
      - UserComments
      - ReportedBy
      - ReportedDateTime
    example:
      ID: 11367
      ErrorContent: "Operation is not valid due to the current state of the object."
      ErrorType: "Exception"
      UserComments: "Was clicking this and that and then Boom!"
      ReportedBy: "domain\\name"
      ReportedDateTime: "2016-01-19 14:07:00"
  reports:
    properties:
      message:
        type: string
      reports:
        type: array
        items:
          $ref: '#/definitions/report'
    example:
      message: "success"
      reports:
        - $ref: '#/definitions/report'

但是，在 Swagger UI 中，上述结果...

  "message": "success",
  "reports": [
    
      "$ref": "#/definitions/report"
    
  ]

一个有趣的提示，在 Swagger UI 中，当我查看模型视图时，它确实包含所有 report 甚至带有描述。

【参考方案1】：

这种行为是正确的——examples 部分不能被 JSON 指针引用。有关当前支持的内容，请参阅 OAI Specification。

如果您认为这是一个常见的用例，请在规范存储库中打开一个问题。

【讨论】：

谢谢！我会打开一个错误。如果没有这个改变，我必须在多个地方重复示例。