How to handle multi level array as input parameter from custom POST webservice in Magento2

Question

We have request to create custom REST webservice for creating gift orders and we are successfully able to create order for single item but facing issues on taking multi items as input.

Can anyone help please?

We have created below files to handle

1. CreateOrderInterface

   interface CreateOrderInterface
   {
   
       /**
        * @param string $giftCardCode
        * @return boolean;
        * @throws \Exception
        */
       public function checkGiftCard($giftCardCode);
   
       /**
        * @param XYZ\GiftCard\Api\JsondataInterface $orderData
        * @param XYZ\GiftCard\Api\AddressdataInterface $customerAddress
        * @param XYZ\GiftCard\Api\BillingdataInterface $billingAddress
        * @param XYZ\GiftCard\Api\ShippingdataInterface $shippingAddress
        * @param XYZ\GiftCard\Api\ItemsdataInterface $items
        * @return string;
        * @throws \Exception
        */
       public function createOrder($orderData, $customerAddress,$billingAddress,$shippingAddress,$items);
   }
   

2. createOrder Model

   class createOrder
   {
       /**
        * @param \XYZ\GiftCard\Api\Kensium\GiftCard\Api\JsondataInterface $jsonOrderData
        * @param \XYZ\GiftCard\Api\Kensium\GiftCard\Api\AddressdataInterface $customerAddress
        * @param \XYZ\GiftCard\Api\Kensium\GiftCard\Api\BillingdataInterface $billingAddress
        * @param \XYZ\GiftCard\Api\Kensium\GiftCard\Api\ShippingdataInterface $shippingAddress
        * @param \XYZ\GiftCard\Api\Kensium\GiftCard\Api\ItemsdataInterface $items
        * @return array|string
        * @throws \Exception
        * @throws \Magento\Framework\Exception\LocalizedException
        * @throws bool
        */
       public function createOrder($jsonOrderData, $customerAddress, $billingAddress, $shippingAddress,$items)
       {
           $invalidType = array();
           $invalidSku = array();
           $invalidAmount = array();
           print_r($jsonOrderData->getItems());die;
       }
   }
   

Answer 1

To pass an array of items annotation should be specified in the following format:

@param \XYZ\GiftCard\Api\ItemsdataInterface[] $items

Square brackets here mean, that you are passing an indexed array containing objects of \XYZ\GiftCard\Api\ItemsdataInterface type.

One more note regarding @return array|string, all parameters/return values in Magento 2 web API must be concrete types, it is not allowed to specify types like int|string for example. It is possible however to use string|null, which means that this value is optional. Also array should never be used, instead use string[], \Custom\Type[] which would let the system know array of which types is declared.