Open API继承了示例数据

Question

我正在使用OpenAPI 3.0为我正在构建的服务定义API。我遇到了重用其他组件中的架构组件的问题。例如，我有一个Note对象，其中包含创建该笔记的人的Profile对象。通过使用Profile关键字引用$ref对象，这可以正常工作。问题是当显示示例时没有任何配置文件的数据，如果我将ref放在如下的示例中，它包括Profile的实际OpenAPI块，而不仅仅是Profile组件的示例数据。

我想知道是否有一种方法可以重用其他组件中的组件，并重用这些组件上的示例集？

例如：

FullNote:
  allOf:
    - $ref: '#/components/schemas/BaseNote'
    - type: object
      title: A single note response
      required:
      - id
      - dateCreated
      - profile
      properties:
        id:
          type: integer
          format: int32
        dateCreated:
          type: integer
          format: int64
        profile:
          type: object
          $ref: '#/components/schemas/Profile'
      example:
        id: 123456789
        dateCreated: 1509048083045
        profile:
          $ref: '#/components/schemas/Profile'

Answer 1

example关键字（不要与exampleS混淆）不支持$ref。整个示例需要内联指定：

    FullNote:
      allOf:
        - $ref: '#/components/schemas/BaseNote'
        - type: object
          ...
          example:
            id: 123456789
            dateCreated: 1509048083045
            influencer:
              prop1: value1  # <----
              prop2: value2

或者，您可以使用属性级示例 - 在这种情况下，像Swagger UI这样的工具将从属性示例构建架构示例。

    FullNote:
      allOf:
        - $ref: '#/components/schemas/BaseNote'
        - type: object
          ...
          properties:
            id:
              type: integer
              format: int32
              example: 123456789      # <----
            dateCreated:
              type: integer
              format: int64
              example: 1509048083045  # <----
            profile:
              # This property will use examples from the Profile schema
              $ref: '#/components/schemas/Profile'
    Profile:
      type: object
      properties:
        prop1:
          type: string
          example: value1   # <----