打开 API 继承的示例数据

Question

我正在使用 OpenAPI 3.0 为我正在构建的服务定义 API。我运行遇到了在其他组件中重用架构组件的问题。例如，我有一个 Note 对象，其中包含创建笔记的人的 Profile 对象。通过使用 $ref 关键字引用 Profile 对象，这按预期工作。问题是在显示示例时，配置文件没有任何数据，如果我将 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   # <----

打开 API 继承的示例数据

Open API inherited example data

yaml

swagger

api-design

openapi