开放API继承示例数据

问题描述

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

I'm using OpenAPI 3.0 to define an API for a service I am building. I'm running into an issue reusing schema components inside other components. For example, I have a Note object which contains a Profile object of the person who created the note. This works as expected by referencing the Profile object using the $ref keyword. The issue is when showing the example there isn't any data for the profile, and if I place the ref in the example like below it includes the actual OpenAPI block of Profile not just the example data for the Profile component.

我想知道是否有一种方法可以在其他组件中重用组件并重用在这些组件上设置的示例?

I'm wondering if there is a way of reusing components in other components and also reusing the example set on those components?

例如:

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'

推荐答案

example 关键字(不要与 exampleS 混淆)不支持 $ref.整个示例需要内联指定:

The example keyword (not to be confused with exampleS) does NOT support $ref. The whole example needs to be specified inline:

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

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

Alternatively, you can use property-level examples - in this case tools like Swagger UI will build the schema example from property examples.

    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继承示例数据的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！