Improve the descriptions of request bodies

api_docs/swagger/components/requestBodies/partner_order_payload.yaml

@@ -1,4 +1,3 @@
-description: Payload to create an OEM partner order on SCC API.
 required: true
 content:
   application/json:
@@ -8,7 +7,7 @@ content:
         partner_order:
           required: true
           type: object
-          description: Main object containing all required data to create an order.
+          description: Object which represents the order to be placed.
           properties:
             oem_token:
               $ref: '/swagger/components/requestBodies/fields.yaml#/oem_token'
@@ -22,3 +21,45 @@ content:
               description: List of all order items.
               items:
                 $ref: '/swagger/components/requestBodies/partner_order_item_payload.yaml'
+description: |-
+  Payload to create an OEM partner order on SCC API.
+
+  The request's payload *must* contain a JSON object that *should* correspond to
+  a single order.
+
+  At the root of the main JSON object, there *must* be an unique key named
+  `"partner_order"`, whose value *should* be an JSON object representing an OEM
+  partner order, containing the following keys:
+
+    - `"oem_token"`: string, **required**
+
+      Value *must* be a string, with a maximum length of 255 characters.
+      It *should not* be empty, and must be unique per OEM partner at the moment
+      of placing a new order. It is generated and kept by the OEM partner.
+
+    - `"purchased_at"`: string, **required**
+
+      Value *must* be a string, ISO8601-formatted. It must be older than the
+      current date and time (cannot be a moment in the future). It represents
+      the date and time at which the customer placed the order with the OEM
+      partner.
+
+    - `"email"`: string, *optional*
+
+      Value *must* be a string, email-formatted. The key-value pair *may* be
+      ommited. It represents the customer's email address to be notified aboutt
+      activated subscriptions.
+
+    - `"partner_order_items"`: array of JSON objects, **required**
+
+      Value *must* be an array of JSON objects representing the order items.
+      Those objects *should* contain the following keys:
+
+        - `"sku"`: string, **required**
+
+          Value *must* be a string and *must* match a valid SUSE SKU.
+
+        - `"system_limit"`: integer, **required**
+
+          Value *must* be an integer greater than one. It represents the maximum
+          number of systems which can use the given SKU simultaneously.

api_docs/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml

@@ -1,4 +1,3 @@
-description: Partner order object
 required: true
 content:
   application/json:
@@ -24,3 +23,59 @@ content:
               description: List of all order items.
               items:
                 $ref: '/swagger/components/requestBodies/pre_activation/partner_order_item_payload.yaml'
+description: |-
+  Payload to create an OEM partner order and pre-activate it on SCC API.
+
+  The request's payload *must* contain a JSON object that *should* correspond to
+  a single order.
+
+  At the root of the main JSON object, there *must* be an unique key named
+  `"partner_order"`, whose value *should* be an JSON object representing an OEM
+  partner order, containing the following keys:
+
+    - `"oem_token"`: string, **required**
+
+      Value *must* be a string, with a maximum length of 255 characters.
+      It *should not* be empty, and must be unique per OEM partner at the moment
+      of placing a new order. It is generated and kept by the OEM partner.
+
+    - `"purchased_at"`: string, **required**
+
+      Value *must* be a string, ISO8601-formatted. It must be older than the
+      current date and time (cannot be a moment in the future). It represents
+      the date and time at which the customer placed the order with the OEM
+      partner.
+
+    - `"end_user_account_number"`: string, **required**
+
+      Value *must* be a string which identifies the end user (customer) within
+      the SCC domain. It *must* be either the end user's UC site ID or the end
+      user's Sales Force account number. It *should* be informed by the end user
+      to the OEM partner prior to placing an order to SUSE.
+
+    - `"email"`: string, *optional*
+
+      Value *must* be a string, email-formatted. The key-value pair *may* be
+      ommited. It represents the customer's email address to be notified aboutt
+      activated subscriptions.
+
+    - `"partner_order_items"`: array of JSON objects, **required**
+
+      Value *must* be an array of JSON objects representing the order items.
+      Those objects *should* contain the following keys:
+
+        - `"sku"`: string, **required**
+
+          Value *must* be a string and *must* match a valid SUSE SKU.
+
+        - `"system_limit"`: integer, **required**
+
+          Value *must* be an integer greater than one. It represents the maximum
+          number of systems which can use the given SKU simultaneously.
+
+        - `"starts_at"`: string, *optional*
+
+          Value *must* be a string, ISO8601-formatted. It *must* be newer than
+          the current date and time (cannot be a moment in the past). It is used
+          to define the start date of a SKU lifetime. If omited, the lifetime
+          starts once SCC successfully activates the order item.

api_docs/swagger/components/requestBodies/renewal/partner_order_payload.yaml

@@ -0,0 +1,79 @@
+required: true
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        partner_order:
+          required: true
+          type: object
+          description: Object which represents the order to be renewed.
+          properties:
+            oem_token:
+              $ref: '/swagger/components/requestBodies/fields.yaml#/oem_token'
+            purchased_at:
+              $ref: '/swagger/components/requestBodies/fields.yaml#/purchased_at'
+            email:
+              $ref: '/swagger/components/requestBodies/fields.yaml#/email'
+            partner_order_items:
+              required: true
+              type: array
+              description: List of order items to be changed.
+              items:
+                $ref: '/swagger/components/requestBodies/partner_order_item_payload.yaml'
+description: |-
+  Payload to renew an existing OEM partner order on SCC API.
+
+  The request's payload *must* contain a JSON object that *should* correspond to
+  a single order.
+
+  At the root of the main JSON object, there *must* be an unique key named
+  `"partner_order"`, whose value *should* be an JSON object representing an OEM
+  partner order, containing the following keys:
+
+    - `"oem_token"`: string, **required**
+
+      Value *must* be a string, with a maximum length of 255 characters.
+      It *should not* be empty. The informed token *should* match one of an
+      existing order placed by the OEM partner. This means that renewals
+      *should* only be applied to existing orders whose subscriptions are active.
+
+    - `"purchased_at"`: string, **required**
+
+      Value *must* be a string, ISO8601-formatted. It must be older than the
+      current date and time (cannot be a moment in the future). It represents
+      the date and time at which the customer placed the order with the OEM
+      partner.
+
+    - `"email"`: string, *optional*
+
+      Value *must* be a string, email-formatted. The key-value pair *may* be
+      ommited. It represents the customer's email address to be notified aboutt
+      activated subscriptions.
+
+    - `"partner_order_items"`: array of JSON objects, **required**
+
+      Value *must* be an array of JSON objects representing the order items.
+      It *may* be empty if there are no items to be changed. Those objects
+      *should* contain the following keys:
+
+        - `"sku"`: string, **required**
+
+          Value *must* be a string and *must* match a valid SUSE SKU. Renewal
+          orders *should* only contain SKUs that match active subscriptions from
+          the initial order.
+
+          E.g., suppose an initial order which contains exactly the order items
+          **SUSE-SKU-PRODUCT-A-1Y** and **SUSE-SKU-PRODUCT-B-1Y*,* both 1-year
+          subscriptions. A renewal order *may* contain the same SKUs or SKUs
+          which related to the same products, like **SUSE-SKU-PRODUCT-A-3Y**
+          (3 years) or **SUSE-SKU-PRODUCT-B-5Y** (5 years), but not a SKU for a
+          new subscription, like **SKU-PRODUCT-C-1Y** for product C, which is
+          not included in the initial order.
+
+        - `"system_limit"`: integer, **required**
+
+          Value *must* be an integer greater than one. It represents the maximum
+          number of systems which can use the given SKU simultaneously. It *may*
+          be different from values of a previous order, meaning the system limit
+          for a given SKU *may* be updated.

api_docs/swagger/paths/partner_orders.yaml

@@ -27,8 +27,8 @@ post:
   requestBody:
     $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderPayload'
   responses:
-    '200':
-      description: Partner order created successfully.
+    '201':
+      description: Created
       content:
         application/json:
           schema:

api_docs/swagger/paths/partner_orders/renewal.yaml

@@ -13,7 +13,7 @@ post:
     only to extend the lifespan of active subscriptions and/or change the system
     limits.
   requestBody:
-    $ref: '/swagger/swagger.yaml#/components/requestBodies/PartnerOrderPayload'
+    $ref: '/swagger/swagger.yaml#/components/requestBodies/RenewalPartnerOrderPayload'
   responses:
     '200':
       description: Partner order created successfully.

api_docs/swagger/swagger.yaml

@@ -71,6 +71,8 @@ components:
       $ref: "/swagger/components/requestBodies/partner_order_payload.yaml"
     PreActivationPartnerOrderPayload:
       $ref: "/swagger/components/requestBodies/pre_activation/partner_order_payload.yaml"
+    RenewalPartnerOrderPayload:
+      $ref: "/swagger/components/requestBodies/renewal/partner_order_payload.yaml"
   schemas:
     PartnerOrder:
       $ref: "/swagger/components/schemas/partner_order.yaml"