docs: improving openapi docs (#1738)

improve openapi docs, documentaing returned 
null instead of empty array

openapi/Swarm.yaml

@@ -40,6 +40,7 @@ paths:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
       requestBody:
         content:
           application/octet-stream:
@@ -56,6 +57,8 @@ paths:
             application/json:
               schema:
                 $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
+        "400":
+          $ref: "SwarmCommon.yaml#/components/responses/400"
         "403":
           $ref: "SwarmCommon.yaml#/components/responses/403"
         "500":
@@ -131,6 +134,7 @@ paths:
       parameters:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
       requestBody:
         content:
           application/octet-stream:
@@ -179,6 +183,7 @@ paths:
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCollection"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmIndexDocumentParameter"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmErrorDocumentParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
       requestBody:
         content:
           multipart/form-data:
@@ -553,6 +558,7 @@ paths:
             $ref: "SwarmCommon.yaml#/components/schemas/PssRecipient"
           required: false
           description: Recipient publickey
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
       responses:
         "201":
           description: Subscribed to topic
@@ -567,7 +573,7 @@ paths:
     get:
       summary: Subscribe for messages on the given topic.
       tags:
-        - Pss subscribe
+        - Postal Service for Swarm
       parameters:
         - in: path
           name: topic
@@ -649,6 +655,7 @@ paths:
           required: false
           description: "Feed indexing scheme (default: sequence)"
         - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
+        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
       responses:
         "201":
           description: Created
@@ -718,7 +725,7 @@ paths:
     get:
       summary: Get all available stamps for this node
       tags:
-        - Get stamp batches
+        - Postage Stamps
       responses:
         "200":
           description: Returns an array of all available postage batches.
@@ -741,7 +748,7 @@ paths:
     get:
       summary: Get an individual postage batch status
       tags:
-        - Get stamp batch
+        - Postage Stamps
       responses:
         "200":
           description: Returns an individual postage batch state
@@ -755,23 +762,23 @@ paths:
           description: Default response
 
   "/stamps/{amount}/{depth}":
-    get:
-      summary: Buy a new postage batch
+    post:
+      summary: Buy a new postage batch. \n\n Be aware, this endpoint create an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
       tags:
-        - Buy stamp batch
+        - Postage Stamps
       parameters:
         - in: path
           name: amount
           schema:
             type: integer
           required: true
-          description: Amount added to the balance
+          description: Amount of BZZ added that the postage batch will have.
         - in: path
           name: depth
           schema:
             type: integer
           required: true
-          description: Batch depth. Must be higher than default bucket depth (16)
+          description: Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16)
         - in: query
           name: label
           schema:

openapi/SwarmCommon.yaml

@@ -50,19 +50,6 @@ components:
           items:
             $ref: "#/components/schemas/Balance"
 
-    BzzChunksPinned:
-      type: object
-      properties:
-        chunks:
-          type: array
-          items:
-            type: object
-            properties:
-              address:
-                type: string
-              pinCounter:
-                type: integer
-
     BzzTopology:
       type: object
       properties:
@@ -106,9 +93,11 @@ components:
       type: object
       properties:
         lastcheques:
-          type: array
-          items:
-            $ref: "#/components/schemas/ChequePeerResponse"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - type: array
+              items:
+                $ref: "#/components/schemas/ChequePeerResponse"
 
     ChequePeerResponse:
       type: object
@@ -149,6 +138,10 @@ components:
       type: string
       pattern: "^[A-Fa-f0-9]{40}$"
       example: "36b7efd913ca4cf880b8eeac5093fa27b0825906"
+      
+    EmptyNull:
+      type: 'null'
+      description: When no entries 'null' is returned instead of empty array.
 
     FileName:
       type: string
@@ -221,9 +214,11 @@ components:
       type: object
       properties:
         tags:
-          type: array
-          items:
-            $ref: "#/components/schemas/NewTagResponse"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - type: array
+              items:
+                $ref: "#/components/schemas/NewTagResponse"
 
     P2PUnderlay:
       type: string
@@ -233,9 +228,11 @@ components:
       type: object
       properties:
         peers:
-          type: array
-          items:
-            $ref: "#/components/schemas/Address"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - type: array
+              items:
+                $ref: "#/components/schemas/Address"
 
     PssRecipient:
       type: string
@@ -259,7 +256,9 @@ components:
       type: object
       properties:
         stamps:
-          $ref: "#/components/schemas/PostageBatches"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - $ref: "#/components/schemas/PostageBatches"
 
     BatchIDResponse:
       type: object
@@ -319,9 +318,11 @@ components:
         totalSent:
           type: integer
         settlements:
-          type: array
-          items:
-            $ref: "#/components/schemas/Settlement"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - type: array
+              items:
+                $ref: "#/components/schemas/Settlement"
 
     SwarmAddress:
       type: string
@@ -356,9 +357,11 @@ components:
       type: object
       properties:
         addresses:
-          type: array
-          items:
-            $ref: "#/components/schemas/SwarmOnlyReference"
+          oneOf:
+            - $ref: '#/components/schemas/EmptyNull'
+            - type: array
+              items:
+                $ref: "#/components/schemas/SwarmOnlyReference"
 
     SwarmReference:
       oneOf:
@@ -531,6 +534,14 @@ components:
       required: false
       description: Upload file/files as a collection
 
+    SwarmPostageBatchId:
+      in: header
+      name: swarm-postage-batch-id
+      description: "ID of Postage Batch that is used to upload data with"
+      required: true
+      schema:
+        $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
+
   responses:
     "204":
       description: The resource was deleted successfully.