diff --git a/api/swagger.yaml b/api/swagger.yaml
index 1cabb9b516b3cff3fc772ac4bb9a7916986be59e..dc8a430b8319299321272ea7b13ddd84f1a850a9 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -9360,7 +9360,10 @@ paths:
 
         - name: "version"
           in: "query"
-          description: "The version number of the service object being updated. This is required to avoid conflicting writes."
+          description: "The version number of the service object being updated.
+          This is required to avoid conflicting writes.
+          This version number should be the value as currently set on the service *before* the update.
+          You can find the current version by calling `GET /services/{id}`"
           required: true
           type: "integer"
         - name: "registryAuthFrom"