arrays - Swagger 嵌套对象数组

Question

我被要求使用 swagger 来描述 API，我很难让更复杂的情况发挥作用。想象一下，您正在发布具有多个订单项目的订单

<upload_order>
<token>d6a91238b0f17b49d49fbdcbba773d71</token>
<order>
    <order_id>10006</order_id>
    <item_value>48.50</item_value>
    <postage_value>5.00</postage_value>
    <gross_value>A43.50</gross_value>
    <discount_value>10.00</discount_value>
    <delivery_date>2016-10-32</delivery_date>
    <customer_name>Tom H</customer_name>
    <business_name>Toysorry</business_name>
    <address_line_1>Adderss Line 1</address_line_1>
    <address_line_2>Adderss Line 1</address_line_2>
    <town>Town</town>
    <county>County</county>
    <postcode>PO123ST</postcode>
    <email>email@email.com</email>
    <telephone>0787878787878</telephone>
    <delivery_instructions>Garage</delivery_instructions>
    <delivery_method>PRE12</delivery_method>
    <items>
        <item>
            <id>1</id>
            <sku>BLABLA</sku>
            <qty>A</qty>
            <product_name>A Product</product_name>
            <unit_price>1.50</unit_price>
        </item>
        <item>
            <id>2</id>
            <sku>HAHAHA</sku>
            <qty>2</qty>
            <product_name>WINTER BUNDLE</product_name>
            <unit_price>22.00</unit_price>
        </item>
    </items>
</order>

我如何用 swagger 来描述它，因为以这种方式使用数组似乎并没有发挥作用

/upload_order:
post:
  description: create order
  operationId: upload_order
  produces:
    - application/xml
  parameters:
    - name: upload_order
      in: body
      description: upload order
      required: true
      schema:
        $ref: '#/definitions/newOrder'
  responses:
    '200':
      description: response
      schema:
        $ref: '#/definitions/token_response'
    default:
      description: unexpected error
      schema:
        $ref: '#/definitions/errorModel'



newOrder:
    type: object
    required:
      - token
      - order_id
      - item_value
      - postage_value
      - gross_value
      - discount_value
      - delivery_date
      - customer_name
      - business_name
      - address_line_1
      - address_line_2
      - town
      - county
      - postcode
      - email
      - telephone
      - delivery_instructions
      - delivery_method
      - items
    properties:
      token:
        type: string
      order_id:
        type: string
      item_value:
        type: number
        format: float
      postage_value:
        type: number
        format: float
      gross_value:
        type: number
        format: float
      discount_value:
        type: number
        format: float
      delivery_date:
        type: string
        format: date
      customer_name:
        type: string
      business_name:
        type: string
      address_line_1:
        type: string
      address_line_2:
        type: string
      town:
        type: string
      county:
        type: string
      postcode:
        type: string
      email:
        type: string
      telephone:
        type: string
      delivery_instructions:
        type: string
      delivery_method:
        type: string
      items:
        $ref: '#/definitions/itemsArray'
  itemsArray:
    type: array
    required: item
    item:
      $ref: '#/definitions/item'
  item:
    required:
      - id
      - sku
      - qty
      - product_name
      - unit_price
    type: object
    properties:
      id:
        type: string
      sku:
        type: string
      qty:
        type: integer
        format: int32
      product_name:
        type: string
      unit_price:
        type: number
        format: float

请救救我

谢谢

更新 - 我根据完整的宠物店标记估计几天后，忘记发布答案，对某些人来说很容易

paths:
  /upload_order:
    post:
      description: create order
      operationId: upload_order
      parameters:
        - name: upload_order
          in: body
          description: upload order
          required: true
          schema:
            $ref: '#/definitions/uploadOrder'
      responses:
        '200':
          description: response
          schema:
            $ref: '#/definitions/upload_response'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
definitions:
  uploadOrder:
    type: object
    required:
      - upload_order
    properties:
      upload_order:
        $ref: '#/definitions/uploadOrderData'
  uploadOrderData:
    type: object
    required:
      - login
      - order
    properties:
      login:
        $ref: '#/definitions/login'
      order:
        $ref: '#/definitions/order'
  order:
    type: object
    required:
      - order_id
      - address_line_2
      - items
    properties:
      order_id:
        type: string
      item_value:
        type: string
        pattern: '^(\d{1,100}\.\d{2})$'
        default: '0.00'
      postage_value:
        type: string
        pattern: '^(\d{1,100}\.\d{2})$'
        default: '0.00'
      gross_value:
        type: string
        pattern: '^(\d{1,100}\.\d{2})$'
        default: '0.00'
      discount_value:
        type: string
        pattern: '^(\d{1,100}\.\d{2})$'
        default: '0.00'
      delivery_date:
        type: string
        format: date
      customer_name:
        type: string
      business_name:
        type: string
      address_line_1:
        type: string
      address_line_2:
        type: string
      town:
        type: string
      county:
        type: string
      postcode:
        type: string
      email:
        type: string
      telephone:
        type: string
      delivery_instructions:
        type: string
      delivery_method:
        type: string
      items:
        $ref: '#/definitions/orderItems'
  orderItems:
    type: array
    required:
      - item
    properties:
      item:
        $ref: '#/definitions/orderItem'
    items:
      $ref: '#/definitions/orderItem'
  orderItem:
    required:
      - id
      - sku
      - qty
      - product_name
      - unit_price
    type: object
    properties:
      id:
        type: string
      sku:
        type: string
      qty:
        type: integer
        format: int32
      product_name:
        type: string
      unit_price:
        type: string
        pattern: '^(\d{1,100}\.\d{2})$'
        default: '0.00'
  login:
    type: object
    required:
      - login
    properties:
      login:
        $ref: '#/definitions/login_data'
  login_data:
    type: object
    required:
      - username
      - password
      - channel_code
    properties:
      username:
        type: string
      password:
        type: string
      channel_code:
        type: string
  upload_response:
    type: object
    properties:
      response:
        $ref: '#/definitions/upload_response_data'
  upload_response_data:
    type: object
    required:
      - messages
      - success
    properties:
      messages:
        $ref: '#/definitions/messages'
      success:
        type: string
  errorModel:
    type: object
    required:
      - messages
    properties:
      messages:
        $ref: '#/definitions/messages'
  messages:
    type: array
    required:
      - message
    properties:
      message:
        $ref: '#/definitions/message'
    items:
      $ref: '#/definitions/message'
  message:
    type: string

Answer 1

根据您的 XML 文档，您似乎不需要类型 itemsArray .您可以尝试简化 newOrder 的定义通过引用 item输入 items直接地。以下是修改后的类型定义的相关部分。

definitions:
  newOrder:
      type: object
      ...
      properties:
        ...
        delivery_method:
          type: string
        items:
          type: array
          items:
            $ref: '#/definitions/item'

  item:
      ...
      type: object
      properties:
        id:
          type: string
        ...

生成的数据结构如下所示: http://i.stack.imgur.com/MyjpD.png

附加说明:如 token在 order 之外XML 文档中的元素，您可能需要拆分 newOrder输入两个并移动 token到外部元素。为了让您有一个想法，这里有一个示例，其中除标记之外的所有属性都移至嵌套元素 order .

  newOrder:
    properties:
      token:
        type: string
      order:
        type: array
        items:
          $ref: '#/definitions/order'
  order:
    properties:
      order_id:
        type: string
      ...

结果类型定义: http://i.stack.imgur.com/P12Ah.png