Improve documentation of `Version` usage for Swarm API

This fix is an attempt to improve the documentation of
`Version` usage for Swarm API in Swagger docs.

As is shown in the docs updates, `Version` field in Swarm
API is a way to ensure safe concurrency and determinism
so that multiple updates to the same swarm related objects
(Node, Service, etc) will not unintentially overwrite each other.

This fix fixes 29448.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>

api/swagger.yaml

@@ -1577,6 +1577,21 @@ definitions:
           Settable: null
           Value: []
 
+  ObjectVersion:
+    description: |
+      The version number of the object such as node, service, etc. This is needed to avoid conflicting writes.
+      The client must send the version number along with the modified specification when updating these objects.
+      This approach ensures safe concurrency and determinism in that the change on the object
+      may not be applied if the version number has changed from the last read. In other words,
+      if two update requests specify the same base version, only one of the requests can succeed.
+      As a result, two separate update requests that happen at the same time will not
+      unintentially overwrite each other.
+    type: "object"
+    properties:
+      Index:
+        type: "integer"
+        format: "int64"
+
   NodeSpec:
     type: "object"
     properties:
@@ -1613,11 +1628,7 @@ definitions:
       ID:
         type: "string"
       Version:
-        type: "object"
-        properties:
-          Index:
-            type: "integer"
-            format: "int64"
+        $ref: "#/definitions/ObjectVersion"
       CreatedAt:
         type: "string"
         format: "dateTime"
@@ -1840,11 +1851,7 @@ definitions:
         description: "The ID of the swarm."
         type: "string"
       Version:
-        type: "object"
-        properties:
-          Index:
-            type: "integer"
-            format: "int64"
+        $ref: "#/definitions/ObjectVersion"
       CreatedAt:
         type: "string"
         format: "dateTime"
@@ -2030,11 +2037,7 @@ definitions:
         description: "The ID of the task."
         type: "string"
       Version:
-        type: "object"
-        properties:
-          Index:
-            type: "integer"
-            format: "int64"
+        $ref: "#/definitions/ObjectVersion"
       CreatedAt:
         type: "string"
         format: "dateTime"
@@ -2242,11 +2245,7 @@ definitions:
       ID:
         type: "string"
       Version:
-        type: "object"
-        properties:
-          Index:
-            type: "integer"
-            format: "int64"
+        $ref: "#/definitions/ObjectVersion"
       CreatedAt:
         type: "string"
         format: "dateTime"
@@ -2454,11 +2453,7 @@ definitions:
       ID:
         type: "string"
       Version:
-        type: "object"
-        properties:
-          Index:
-            type: "integer"
-            format: "int64"
+        $ref: "#/definitions/ObjectVersion"
       CreatedAt:
         type: "string"
         format: "dateTime"