diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml
index 14b5e4864c..fc9ecd39bc 100644
--- a/components/engine/api/swagger.yaml
+++ b/components/engine/api/swagger.yaml
@@ -2698,6 +2698,11 @@ paths:
   /containers/json:
     get:
       summary: "List containers"
+      description: |
+        Returns a list of containers. For details on the format, see [the inspect endpoint](#operation/ContainerInspect).
+
+        Note that it uses a different, smaller representation of a container than inspecting a single container. For example,
+        the list of linked containers is not propagated .
       operationId: "ContainerList"
       produces:
         - "application/json"