如何在OpenAPI 3中引用数组项目示例? [英] How to reference array item examples in OpenAPI 3?

问题描述

使用此架构定义:

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)的一部分重用Holmes示例.但是，如果我使用引用的示例:

Now I'd like to reuse the Holmes example for both the single user (ContactModel1) and as part of an array of users (AllContacts). But if I use the referenced examples:

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

我在Swagger用户界面中得到了这个意外的结果:

I get this unexpected result in Swagger UI:

[
  {
    "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

I am using this doc as reference:
https://swagger.io/docs/specification/adding-examples/#reuse

推荐答案

这不是有效的定义:

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

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

1) The example syntax is wrong. OpenAPI 3.0 has two keywords for examples - example (singular) and examples (plural). They work differently:

• example需要一个内联示例，并且不支持$ref .
• examples是命名示例的映射(集合).它支持$ref-但是您只能$ref整个示例，而不是示例的各个部分.这也意味着不可能从多个$ref构建示例.请注意，并非所有元素都支持复数examples.

• example requires an inline example and does not support $ref.
• examples is a map (collection) of named examples. It supports $ref - but you can only $ref whole examples, not individual parts of an example. This also means it's not possible to build an example from multiple $refs. Note that not all elements support plural examples.

Swagger UI用户注意:Swagger UI当前支持example(单数)，但不支持examples(复数).在此问题中跟踪了对examples的支持.

Note for Swagger UI users: Swagger UI currently supports example (singular) but not examples (plural). Support for examples is tracked in this issue.

2)架构对象仅支持单数example，但不支持复数examples.换句话说，方案仅支持内联示例.

2) The Schema Object only supports singular example but not plural examples. In other words, schemas support inline examples only.

3)在OpenAPI 3.0中，架构引用使用格式#/components/schemas/...，而不是#/definitions/...

3) In OpenAPI 3.0, schema references use the format #/components/schemas/..., not #/definitions/...

我想在两种情况下(用户数组和单个用户)对Holmes使用相同的Example定义.

I'd like to use the same EXAMPLE definition for Holmes in both cases, the array of users and the single user.

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

There's no way to reuse a part of an example in this case. You'll have to repeat the example value in both schemas:

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

这篇关于如何在OpenAPI 3中引用数组项目示例?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！