From 37851d8f5bb7a86d8b393632ac00b7e6953ce5bf Mon Sep 17 00:00:00 2001
From: Hannes Ljungberg <hannes@5monkeys.se>
Date: Thu, 11 Jul 2019 16:12:52 +0200
Subject: [PATCH] Update service networks documentation

The previous description stated that an array of names / ids could be passed when the API in reality expects objects in the form of NetworkAttachmentConfig. This is fixed by updating the description and adding a definition for NetworkAttachmentConfig.

Signed-off-by: Hannes Ljungberg <hannes@5monkeys.se>
(cherry picked from commit 4d09fab232ed282d020afbe1e0935b53379df4ad)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 api/swagger.yaml | 40 +++++++++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 17 deletions(-)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index 4860b7a34d..040ec0f2d2 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -3002,16 +3002,10 @@ definitions:
         description: "Runtime is the type of runtime specified for the task executor."
         type: "string"
       Networks:
+        description: "Specifies which networks the service should attach to."
         type: "array"
         items:
-          type: "object"
-          properties:
-            Target:
-              type: "string"
-            Aliases:
-              type: "array"
-              items:
-                type: "string"
+          $ref: "#/definitions/NetworkAttachmentConfig"
       LogDriver:
         description: "Specifies the log driver to use for tasks created from this spec. If not present, the default one for the swarm will be used, finally falling back to the engine default if not specified."
         type: "object"
@@ -3257,17 +3251,11 @@ definitions:
               - "stop-first"
               - "start-first"
       Networks:
-        description: "Array of network names or IDs to attach the service to."
+        description: "Specifies which networks the service should attach to."
         type: "array"
         items:
-          type: "object"
-          properties:
-            Target:
-              type: "string"
-            Aliases:
-              type: "array"
-              items:
-                type: "string"
+          $ref: "#/definitions/NetworkAttachmentConfig"
+
       EndpointSpec:
         $ref: "#/definitions/EndpointSpec"
 
@@ -4439,6 +4427,24 @@ definitions:
           IP address and ports at which this node can be reached.
         type: "string"
 
+  NetworkAttachmentConfig:
+    description: "Specifies how a service should be attached to a particular network."
+    type: "object"
+    properties:
+      Target:
+        description: "The target network for attachment. Must be a network name or ID."
+        type: "string"
+      Aliases:
+        description: "Discoverable alternate names for the service on this network."
+        type: "array"
+        items:
+          type: "string"
+      DriverOpts:
+        description: "Driver attachment options for the network target"
+        type: "object"
+        additionalProperties:
+          type: "string"
+
 paths:
   /containers/json:
     get: