From 37302166e03d4a442804f8ba83085f4c48ac12c9 Mon Sep 17 00:00:00 2001
From: lee <charlselee58@gmail.com>
Date: Thu, 16 Jul 2026 13:14:37 +0800
Subject: [PATCH] api: document Task.NetworksAttachments in the swagger
 definition

The GET /tasks and GET /tasks/{id} endpoints return a NetworksAttachments
field on each Task (it appears in the response examples and in the Go type
api/types/swarm.Task), but the Task definition in api/swagger.yaml never
declares it as a property, and there is no NetworkAttachment definition.

As a result, clients generated from the swagger (for example bollard for
Rust) silently drop per-task network attachment / address information.

Add the NetworksAttachments property to Task and a NetworkAttachment
definition (Network + Addresses), matching the existing Go type and the
response examples. Documentation only; no behaviour change.

Signed-off-by: lee <charlselee58@gmail.com>
---
 api/swagger.yaml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/api/swagger.yaml b/api/swagger.yaml
index 72cf3de4d8..be373fe54b 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -4969,6 +4969,28 @@ definitions:
       PortStatus:
         $ref: "#/definitions/PortStatus"
 
+  NetworkAttachment:
+    description: |
+      Specifies how a task is attached to a network, and the addresses the
+      task was assigned on that network.
+    type: "object"
+    properties:
+      Network:
+        $ref: "#/definitions/Network"
+      Addresses:
+        description: |
+          The IP addresses (in CIDR notation) assigned to the task on this
+          network. To maintain backward compatibility this field accepts CIDR
+          notation, but only the IP address is used.
+        type: "array"
+        items:
+          type: "string"
+    example:
+      Network:
+        ID: "4qvuz4ko70xaltuqbt8956gd1"
+      Addresses:
+        - "10.255.0.10/16"
+
   Task:
     type: "object"
     properties:
@@ -5013,6 +5035,13 @@ definitions:
           the JobIteration of the Service this Task was created for. Absent if
           the Task was created for a Replicated or Global Service.
         $ref: "#/definitions/ObjectVersion"
+      NetworksAttachments:
+        description: |
+          The networks that this task is attached to, and the addresses the
+          task was assigned on each of them.
+        type: "array"
+        items:
+          $ref: "#/definitions/NetworkAttachment"
     example:
       ID: "0kzzo1i0y4jz6027t0k7aezc7"
       Version: