代码之家 › 专栏 › 技术社区 › David Chen

如何正确引用组件中的示例(OAS 3.0)[重复]

openapi swagger yaml

David Chen · 技术社区 · 6 年前

schemas:
  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      - id: 1
        firstName: Sherlock
        lastName: Holmes
      - id: 2
        firstName: John
        lastName: Watson

我得到了预期的结果:

[
  {
     "id": 1,
     "firstName": "Sherlock",
     "lastName": "Holmes"
  },
  {
     "id": 2,
     "firstName": "John",
     "lastName": "Watson"
  }
]

ContactModel1 )作为用户数组的一部分( AllContacts ). 但如果我用引用的例子:

schemas:

  AllContacts:
    type: array
    items:
      $ref: '#/definitions/ContactModel1'
    example:
      Homes:
        $ref: '#/components/examples/Homes'
      Watson:
        $ref: '#/components/examples/Watson'

  examples:

    Holmes:
      value:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    Watson:
      value:
        id: 2
        first_name: John
        last_name: Watson

我在虚张声势的用户界面中得到了这个意外的结果:

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  },
  {
    "value": {
      "id": 2,
      "first_name": "John",
      "last_name": "Watson",
    },
    "$$ref": "#/components/examples/Watson"
  }
]

一个类似的意外例子 GET /user/1 :

[
  {
    "value": {
      "id": 1,
      "first_name": "Sherlock",
      "last_name": "Holmes",
    },
    "$$ref": "#/components/examples/Holmes"
  }
]

我使用此文档作为参考:
https://swagger.io/docs/specification/adding-examples/#reuse

0 回复 | 直到 6 年前

Helen 6 年前

这不是有效的定义:

components:
  schemas:
    AllContacts:
      type: array
      items:
        $ref: '#/definitions/ContactModel1'
      example:
        Homes:
          $ref: '#/components/examples/Homes'
        Watson:
          $ref: '#/components/examples/Watson'

1) 那个 example 语法错误。例如,OpenAPI 3有两个关键字- (单数)和 examples (复数)。它们的工作方式不同:

例子 $ref .
实例 是命名示例的映射(集合)。它支持 -但是 你只能整个例子,而不是一个例子的个别部分 . 这也意味着不可能从多个 s、注意并非所有元素都支持复数 实例 .

Swagger UI当前支持 例子 实例 (复数)。支持 实例 被跟踪 this issue .

2) 那个 Schema Object 只支持单数 例子 但不是复数 实例 模式仅支持内联示例 .

3) 在OpenAPI 3.0中,模式引用使用以下格式 #/components/schemas/... ,不是 #/definitions/...

在这种情况下,无法重用示例的一部分。必须在两个模式中重复示例值:

components:
  schemas:
    ContactModel1:
      type: object
      properties:
        ...
      example:
        id: 1
        first_name: Sherlock
        last_name: Holmes

    AllContacts:
      type: array
      items:
        $ref: '#/components/schemas/ContactModel1'
      example:
        - id: 1
          first_name: Sherlock
          last_name: Holmes
        - id: 2
          first_name: John
          last_name: Watson