如何定义不同对象的 OpenAPI 有序数组？答案

【问题标题】：How to define an OpenAPI ordered array of different objects?如何定义不同对象的 OpenAPI 有序数组？
【发布时间】：2021-08-20 16:19:14
【问题描述】：

我正在尝试使用 OpenAPI 3.0 版定义我的 API。我正在尝试生成一个包含四个映射的 YAML 文件，每个映射包含不同的信息。如何创建 YAML 文件来实现该目标？我知道我的组件不正确，因此我没有得到正确的结果。

请求正文应该是这样的：

[
  UserInformation{FirstName, LastName},
  AddressInformation{Phone, Address},
  ContactInformation{Email, Phone}
]

openapi: 3.0.0
info:
  version: 1.0.0
  title: 'INPUT-FORM-API'

paths:
  /api/v1/test/healthcheck:
    get:
      summary: Health check for the test api services. Used Internally
      operationId: Externalhealthcheck
      description: healthcheck for the test services status.
      responses:
        '200':
          description: This status is always returned when service is Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthcheckObject'

  /api/v1/test/newformentry:
    post:
      summary: End Point to insert data into the new table.
      operationId: NewFormEntry
      description: EndPoint to insert data for new form.
      requestBody:
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NewFormEntry'
      responses:
        '200':
          description: This status is always returned when service is Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthcheckObject'

components:
  schemas:
    NewFormEntry:
        $ref: '#/components/schemas/UserInformation'
        $ref: '#/components/schemas/AddressInformation'
        $ref: '#/components/schemas/ContactInformation'
        $ref: '#/components/schemas/MessageFromBene'
    UserInformation:
      required:
        - FirstName
        - LastName
      properties:
        FirstName:
          type: string
        LastName:
          type: string
          
    AddressInformation:
      required:
        - StreetAddress
        - City
        - State
        - ZipCode
      properties:
        StreetAddress:
          type: string
        StreetAddress2:
          type: string
        City:
          type: string
        State:
          type: string  
        ZipCode:
          type: integer
          format: int64
          
    ContactInformation:
      required:
        - PhoneNumber
        - Email
      properties:
        PhoneNumber:
          type: integer
          format: int64
          maximum: 9
        Email:
          type: string
        HomePhone:
          type: integer
          format: int64
          maximum: 9
        Cell:
          type: integer
          format: int64
          maximum: 9
        WorkPhone:
          type: integer
          format: int64
          maximum: 9
    
    MessageFromBene:
      required:
        - Message
      properties:
        PhoneNumber:
          type: integer
          format: int64
          maximum: 9
        Message:
          type: string
    
    HealthcheckObject:
      required:
        - Status
        - ErrorMessage
      properties:
        Status:
          type: string
        ErrorMessage:
          type: string

【问题讨论】：

NewFormEntry 定义不正确。那个物体应该是什么？例如。将UserInformation、AddressInformation 和其他对象合并为一个；或这些对象中的一个；还是别的什么？
应该是这些对象的数组。请求应该是 [ {First Name, Last Name}, {Phone Number, Address, Email}] @Helen

标签： swagger openapi

【解决方案1】：

所以NewFormEntry模式必须是一个包含3个对象的数组，其中第一个对象必须是UserInformation，第二个对象必须是AddressInformation，第三个对象mube是ContactInformation。这就像tuple，即元素的有序序列，其中每个元素都有特定的类型。元组定义在不同的 OpenAPI 版本中略有不同。

OpenAPI 3.1

如果或当您迁移到 OAS 3.1 时，可以使用 prefixItems 定义这样的数组。此关键字指定每个元素位置的架构（换句话说，它指定数组中元素的顺序）：

components:
  schemas:
    NewFormEntry:
      type: array
      prefixItems:
        - $ref: '#/components/schemas/UserInformation'    # type of the 1st element
        - $ref: '#/components/schemas/AddressInformation' # type of the 2nd element
        - $ref: '#/components/schemas/ContactInformation' # type of the 3rd element
      minItems: 3
      maxItems: 3
      additionalItems: false   # can be omitted if `maxItems: 3` is specified

OpenAPI 3.0

在 OAS 3.0 中，您可以定义数组长度（即 3 个项）和数组项的可能类型（即每个项可以是 A、B 或 C），但没有办法定义数组中对象的特定顺序。所以你最多可以这样做：

components:
  schemas:
    NewFormEntry:
      type: array
      items:
        oneOf:
          - $ref: '#/components/schemas/UserInformation'
          - $ref: '#/components/schemas/AddressInformation'
          - $ref: '#/components/schemas/ContactInformation'
      minItems: 3
      maxItems: 3

请注意，此定义允许数组中对象的任意顺序以及同一对象的多个实例（例如[UserInformation, UserInformation, UserInformation]）。您可能希望实现额外的后端验证来验证此数组中所需的对象顺序。

【讨论】：