REST API: Add POST /orders/order/{identifier}/shipments (#2292)

Add POST /orders/order/{identifier}/shipments
Fix GET /orders/order/{identifier}/shipments

Author: adriendupuis

docs/api/rest_api/rest_api_reference/input/examples/orders/POST/ShipmentCreate.json.example

@@ -0,0 +1,21 @@
+{
+  "ShipmentCreate": {
+    "identifier": "abc",
+    "ShippingMethod": {
+      "_media-type": "application/vnd.ibexa.api.ShippingMethod+json",
+      "_href": "/api/ibexa/v2/shipping/methods/parcel_locker"
+    },
+    "Amount": {
+      "value": "1922",
+      "currency": "EUR"
+    },
+    "Owner": {
+      "_media-type": "application/vnd.ibexa.api.User+json",
+      "_href": "/api/ibexa/v2/user/users/14"
+    },
+    "Context": {
+      "key1": "value1",
+      "key2": "value2"
+    }
+  }
+}

docs/api/rest_api/rest_api_reference/input/examples/orders/POST/ShipmentCreate.xml.example

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<ShipmentCreate>
+    <identifier>abc</identifier>
+    <ShippingMethod media-type="application/vnd.ibexa.api.ShippingMethod+json" href="/api/ibexa/v2/shipping/methods/parcel_locker"/>
+    <Amount>
+        <value>1922</value>
+        <currency>EUR</currency>
+    </Amount>
+    <Owner media-type="application/vnd.ibexa.api.User+json" href="/api/ibexa/v2/user/users/14"/>
+    <Context>
+        <key1>value1</key1>
+        <key2>value2</key2>
+    </Context>
+</ShipmentCreate>

docs/api/rest_api/rest_api_reference/input/ez-orders.raml

@@ -79,30 +79,53 @@ displayName: Orders
         /shipments:
             get:
                 displayName: Load shipments
-                description: Loads a list of shipments.
+                description: Loads a order's list of shipments.
                 headers:
                     Accept:
                         description: If set, the shipments are returned in XML or JSON format.
                         example:  |
                             application/vnd.ibexa.api.ShipmentRefList+xml
-                    Content-Type:
-                        description: The shipments schema encoded in XML or JSON format.
-                        example:  |
-                            application/vnd.ibexa.api.ShipmentRefList+xml
                 responses:
                     200:
                         description: OK - loads the shipments.
                         body:
-                            application/vnd.ibexa.api.Shipment+xml:
-                                type: Shipment
+                            application/vnd.ibexa.api.ShipmentRefList+xml:
+                                type: ShipmentRefList
                                 example: !include examples/shipments/GET/ShipmentRefList.xml.example
-                            application/vnd.ibexa.api.Shipment+json:
-                                type: Shipment
+                            application/vnd.ibexa.api.ShipmentRefList+json:
+                                type: ShipmentRefList
                                 example: !include examples/shipments/GET/ShipmentRefList.json.example
                     401:
-                        description: Error - the user has no permission to read shipment lists.
+                        description: Error - the user has no permission to read order's shipment lists.
                     404:
-                        description: Error - the shipment does not exist.
+                        description: Error - the order does not exist.
+            post:
+                displayName: Create shipment
+                description: Creates and adds a shipment to an order
+                headers:
+                    Accept:
+                        description: If set, the shipments are returned in XML or JSON format.
+                        example: |
+                            application/vnd.ibexa.api.Shipment+xml
+                            application/vnd.ibexa.api.Shipment+json
+                    Content-Type:
+                        description: The shipments schema encoded in XML or JSON format.
+                        example: |
+                            application/vnd.ibexa.api.ShipmentCreate+xml
+                            application/vnd.ibexa.api.ShipmentCreate+json
+                body:
+                    application/vnd.ibexa.api.ShipmentCreate+xml:
+                        type: ShipmentCreate
+                        example: !include examples/orders/POST/ShipmentCreate.xml.example
+                    application/vnd.ibexa.api.ShipmentCreate+json:
+                        type: ShipmentCreate
+                        example: !include examples/orders/POST/ShipmentCreate.json.example
+                responses:
+                    200:
+                        description: Shipment is created and returned
+                        body:
+                            application/vnd.ibexa.api.Shipment+xml:
+                                type: Shipment
 
     /{id}:
         get:

docs/api/rest_api/rest_api_reference/input/ez-types.raml

@@ -3783,6 +3783,26 @@ Shipment:
         Method:
             type: ShippingMethod
 
+ShipmentRefList:
+    description: 'This class represents a list of Shipments'
+    type: object
+    properties:
+        shipmentRefList:
+            type: Shipment[]
+
+ShipmentCreate:
+    description: 'This class represents the creation of a shipment.'
+    type: object
+    properties:
+        identifier:
+            type: string
+        ShippingMethod:
+            type: ShippingMethod
+        Owner:
+            type: User
+        Context:
+            type: object
+
 ShipmentUpdate:
     description: 'This class represents the update of a shipment.'
     type: object