SONAR-13436 Update Web API docs - user_groups

17 files changed, 113 insertions, 17 deletions

diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/AddUserAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/AddUserAction.java
index 045d1812795..83cbe45e974 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/AddUserAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/AddUserAction.java
@@ -64,7 +64,8 @@ public class AddUserAction implements UserGroupsWsAction {
       .setHandler(this)
       .setPost(true)
       .setSince("5.2")
-      .setChangelog(new Change("6.4", "It's no longer possible to add a user to the default group"));
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
 
     defineGroupWsParameters(action);
     defineLoginWsParameter(action);
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/CreateAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/CreateAction.java
index 29ffb885c39..2992f6aa001 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/CreateAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/CreateAction.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.server.usergroups.ws;
 
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.Request;
 import org.sonar.api.server.ws.Response;
 import org.sonar.api.server.ws.WebService.NewAction;
@@ -64,7 +65,9 @@ public class CreateAction implements UserGroupsWsAction {
       .setHandler(this)
       .setPost(true)
       .setResponseExample(getClass().getResource("create-example.json"))
-      .setSince("5.2");
+      .setSince("5.2")
+      .setChangelog(
+        new Change("8.4", "Field 'id' format in the response changes from integer to string."));
 
     action.createParam(PARAM_ORGANIZATION_KEY)
       .setDescription("Key of organization. If unset then default organization is used.")
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/DeleteAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/DeleteAction.java
index a892c57e898..d8577d44cd2 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/DeleteAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/DeleteAction.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.server.usergroups.ws;
 
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.Request;
 import org.sonar.api.server.ws.Response;
 import org.sonar.api.server.ws.WebService;
@@ -56,7 +57,9 @@ public class DeleteAction implements UserGroupsWsAction {
         PARAM_GROUP_ID, PARAM_GROUP_NAME))
       .setHandler(this)
       .setSince("5.2")
-      .setPost(true);
+      .setPost(true)
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
 
     defineGroupWsParameters(action);
   }
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/GroupWsSupport.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/GroupWsSupport.java
index b25a09ac055..64437873f3d 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/GroupWsSupport.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/GroupWsSupport.java
@@ -36,6 +36,7 @@ import org.sonarqube.ws.UserGroups;
 
 import static com.google.common.base.Preconditions.checkArgument;
 import static java.util.Optional.ofNullable;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_01;
 import static org.sonar.server.exceptions.BadRequestException.checkRequest;
 import static org.sonar.server.exceptions.NotFoundException.checkFound;
 import static org.sonar.server.exceptions.NotFoundException.checkFoundWithOptional;
@@ -162,9 +163,9 @@ public class GroupWsSupport {
 
   private static void defineGroupIdWsParameter(WebService.NewAction action) {
     action.createParam(PARAM_GROUP_ID)
-      .setDeprecatedSince("8.3")
-      .setDescription("Group id")
-      .setExampleValue("42");
+      .setDescription("Group id, use 'name' instead")
+      .setDeprecatedSince("8.4")
+      .setExampleValue(UUID_EXAMPLE_01);
   }
 
   private static void defineGroupNameWsParameter(WebService.NewAction action) {
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/RemoveUserAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/RemoveUserAction.java
index 8ccc9e6b268..4b4d7d19f8e 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/RemoveUserAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/RemoveUserAction.java
@@ -19,6 +19,7 @@
  */
 package org.sonar.server.usergroups.ws;
 
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.Request;
 import org.sonar.api.server.ws.Response;
 import org.sonar.api.server.ws.WebService.NewAction;
@@ -60,7 +61,9 @@ public class RemoveUserAction implements UserGroupsWsAction {
         PARAM_GROUP_ID, PARAM_GROUP_NAME))
       .setHandler(this)
       .setPost(true)
-      .setSince("5.2");
+      .setSince("5.2")
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
 
     defineGroupWsParameters(action);
     defineLoginWsParameter(action);
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
index dc456bfff52..4a2b5cb15f8 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/SearchAction.java
@@ -45,7 +45,6 @@ import static org.apache.commons.lang.StringUtils.defaultIfBlank;
 import static org.sonar.api.utils.Paging.forPageIndex;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.server.es.SearchOptions.MAX_LIMIT;
-import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_GROUP_ID;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_ORGANIZATION_KEY;
 import static org.sonar.server.ws.WsUtils.writeProtobuf;
 import static org.sonarqube.ws.UserGroups.Group;
@@ -82,9 +81,9 @@ public class SearchAction implements UserGroupsWsAction {
       .addPagingParams(100, MAX_LIMIT)
       .addSearchQuery("sonar-users", "names")
       .setChangelog(
+        new Change("8.4", "Field 'id' in the response is deprecated. Format changes from integer to string."),
         new Change("6.4", "Paging response fields moved to a Paging object"),
-        new Change("6.4", "'default' response field has been added"),
-        new Change("8.3", "field " + PARAM_GROUP_ID + "in the response is deprecated"));
+        new Change("6.4", "'default' response field has been added"));
 
     action.createParam(PARAM_ORGANIZATION_KEY)
       .setDescription("Key of organization. If not set then groups are searched in default organization.")
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UpdateAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UpdateAction.java
index 29902c15cd6..6fc48fcf1b3 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UpdateAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UpdateAction.java
@@ -36,6 +36,7 @@ import org.sonarqube.ws.UserGroups;
 
 import static java.lang.String.format;
 import static org.sonar.api.user.UserGroupValidation.GROUP_NAME_MAX_LENGTH;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_01;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.server.exceptions.NotFoundException.checkFound;
 import static org.sonar.server.exceptions.NotFoundException.checkFoundWithOptional;
@@ -67,11 +68,13 @@ public class UpdateAction implements UserGroupsWsAction {
       .setPost(true)
       .setResponseExample(getClass().getResource("update.example.json"))
       .setSince("5.2")
-      .setChangelog(new Change("6.4", "The default group is no longer editable"));
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' format changes from integer to string"),
+        new Change("6.4", "The default group is no longer editable"));
 
     action.createParam(PARAM_GROUP_ID)
       .setDescription("Identifier of the group.")
-      .setExampleValue("42")
+      .setExampleValue(UUID_EXAMPLE_01)
       .setRequired(true);
 
     action.createParam(PARAM_GROUP_NAME)
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UsersAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UsersAction.java
index 51d59895eca..f8e0756bb79 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UsersAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/usergroups/ws/UsersAction.java
@@ -20,6 +20,7 @@
 package org.sonar.server.usergroups.ws;
 
 import java.util.List;
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.Request;
 import org.sonar.api.server.ws.Response;
 import org.sonar.api.server.ws.WebService.NewAction;
@@ -65,7 +66,9 @@ public class UsersAction implements UserGroupsWsAction {
       .setResponseExample(getClass().getResource("users-example.json"))
       .addSelectionModeParam()
       .addSearchQuery("freddy", "names", "logins")
-      .addPagingParams(25);
+      .addPagingParams(25)
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
 
     defineGroupWsParameters(action);
   }
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/create-example.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/create-example.json
index 909f1491ab6..2a276688363 100644
--- a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/create-example.json
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/create-example.json
@@ -1,6 +1,6 @@
 {
   "group": {
-    "id": "42",
+    "id": "AU-Tpxb--iU5OvuD2FLy",
     "organization": "my-org",
     "name": "some-product-bu",
     "description": "Business Unit for Some Awesome Product",
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/search-example.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/search-example.json
index 3749028681f..f165d2a76ee 100644
--- a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/search-example.json
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/usergroups/ws/search-example.json
@@ -6,14 +6,14 @@
   },
   "groups": [
     {
-      "id": 3,
+      "id": "AU-Tpxb--iU5OvuD2FLy",
       "name": "users",
       "description": "Users",
       "membersCount": 17,
       "default": true
     },
     {
-      "id": 4,
+      "id": "AU-Tpxb--iU5OvuD2FLz",
       "name": "administrators",
       "description": "Administrators",
       "membersCount": 2,
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/AddUserActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/AddUserActionTest.java
index bfba587dd9b..d8a3f311775 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/AddUserActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/AddUserActionTest.java
@@ -23,6 +23,8 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.impl.utils.AlwaysIncreasingSystem2;
+import org.sonar.api.server.ws.Change;
+import org.sonar.api.server.ws.WebService.Action;
 import org.sonar.db.DbTester;
 import org.sonar.db.organization.OrganizationDto;
 import org.sonar.db.user.GroupDto;
@@ -39,6 +41,7 @@ import org.sonar.server.ws.WsActionTester;
 
 import static java.net.HttpURLConnection.HTTP_NO_CONTENT;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.api.security.DefaultGroups.ANYONE;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_GROUP_NAME;
@@ -58,6 +61,17 @@ public class AddUserActionTest {
   private WsActionTester ws = new WsActionTester(new AddUserAction(db.getDbClient(), userSession, newGroupWsSupport()));
 
   @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
+  }
+
+  @Test
   public void add_user_to_group_referenced_by_its_id() {
     insertDefaultGroupOnDefaultOrganization();
     GroupDto group = db.users().insertGroup();
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/CreateActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/CreateActionTest.java
index 43e58a54fb6..4d170c77927 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/CreateActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/CreateActionTest.java
@@ -23,6 +23,7 @@ import org.apache.commons.lang.StringUtils;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.WebService;
 import org.sonar.api.utils.System2;
 import org.sonar.core.util.SequenceUuidFactory;
@@ -38,6 +39,7 @@ import org.sonar.server.usergroups.DefaultGroupFinder;
 import org.sonar.server.ws.WsActionTester;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 
 public class CreateActionTest {
@@ -61,6 +63,8 @@ public class CreateActionTest {
     assertThat(action.isPost()).isTrue();
     assertThat(action.responseExampleAsString()).isNotEmpty();
     assertThat(action.params()).hasSize(3);
+    assertThat(action.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Field 'id' format in the response changes from integer to string."));
   }
 
   @Test
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/DeleteActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/DeleteActionTest.java
index 90cec02053a..338877bd6f0 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/DeleteActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/DeleteActionTest.java
@@ -23,6 +23,8 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.impl.utils.AlwaysIncreasingSystem2;
+import org.sonar.api.server.ws.Change;
+import org.sonar.api.server.ws.WebService.Action;
 import org.sonar.api.web.UserRole;
 import org.sonar.db.DbTester;
 import org.sonar.db.component.ComponentDbTester;
@@ -43,6 +45,7 @@ import org.sonar.server.ws.TestResponse;
 import org.sonar.server.ws.WsActionTester;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.core.permission.GlobalPermissions.SYSTEM_ADMIN;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_GROUP_ID;
@@ -63,6 +66,17 @@ public class DeleteActionTest {
   private WsActionTester ws = new WsActionTester(new DeleteAction(db.getDbClient(), userSession, newGroupWsSupport()));
 
   @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
+  }
+
+  @Test
   public void response_has_no_content() {
     addAdmin(db.getDefaultOrganization());
     insertDefaultGroupOnDefaultOrganization();
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/RemoveUserActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/RemoveUserActionTest.java
index fc9a952fe4b..2f5ccc883fc 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/RemoveUserActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/RemoveUserActionTest.java
@@ -23,6 +23,8 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.impl.utils.AlwaysIncreasingSystem2;
+import org.sonar.api.server.ws.Change;
+import org.sonar.api.server.ws.WebService.Action;
 import org.sonar.core.permission.GlobalPermissions;
 import org.sonar.db.DbTester;
 import org.sonar.db.organization.OrganizationDto;
@@ -40,6 +42,7 @@ import org.sonar.server.ws.WsActionTester;
 
 import static java.net.HttpURLConnection.HTTP_NO_CONTENT;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_GROUP_NAME;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_LOGIN;
@@ -59,6 +62,17 @@ public class RemoveUserActionTest {
     new RemoveUserAction(db.getDbClient(), userSession, new GroupWsSupport(db.getDbClient(), defaultOrganizationProvider, new DefaultGroupFinder(db.getDbClient()))));
 
   @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
+  }
+
+  @Test
   public void does_nothing_if_user_is_not_in_group() {
     // keep an administrator
     insertAnAdministratorInDefaultOrganization();
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/SearchActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/SearchActionTest.java
index 6c280aebeef..504125cdefc 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/SearchActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/SearchActionTest.java
@@ -22,6 +22,7 @@ package org.sonar.server.usergroups.ws;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
+import org.sonar.api.server.ws.Change;
 import org.sonar.api.server.ws.WebService;
 import org.sonar.api.utils.System2;
 import org.sonar.db.DbTester;
@@ -64,7 +65,6 @@ public class SearchActionTest {
 
   private WsActionTester ws = new WsActionTester(new SearchAction(db.getDbClient(), userSession, newGroupWsSupport(), new DefaultGroupFinder(db.getDbClient())));
 
-
   @Test
   public void define_search_action() {
     WebService.Action action = ws.getDef();
@@ -72,6 +72,10 @@ public class SearchActionTest {
     assertThat(action.key()).isEqualTo("search");
     assertThat(action.responseExampleAsString()).isNotEmpty();
     assertThat(action.params()).hasSize(5);
+    assertThat(action.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Field 'id' in the response is deprecated. Format changes from integer to string."),
+      tuple("6.4", "Paging response fields moved to a Paging object"),
+      tuple("6.4", "'default' response field has been added"));
   }
 
   @Test
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UpdateActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UpdateActionTest.java
index d13692ce1ff..ef6d51481b9 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UpdateActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UpdateActionTest.java
@@ -22,6 +22,8 @@ package org.sonar.server.usergroups.ws;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
+import org.sonar.api.server.ws.Change;
+import org.sonar.api.server.ws.WebService.Action;
 import org.sonar.api.utils.System2;
 import org.sonar.db.DbTester;
 import org.sonar.db.organization.OrganizationDto;
@@ -36,6 +38,8 @@ import org.sonar.server.usergroups.DefaultGroupFinder;
 import org.sonar.server.ws.TestRequest;
 import org.sonar.server.ws.WsActionTester;
 
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.test.JsonAssert.assertJson;
 
@@ -53,6 +57,18 @@ public class UpdateActionTest {
     new UpdateAction(db.getDbClient(), userSession, new GroupWsSupport(db.getDbClient(), defaultOrganizationProvider, new DefaultGroupFinder(db.getDbClient()))));
 
   @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Parameter 'id' format changes from integer to string"),
+      tuple("6.4", "The default group is no longer editable"));
+  }
+
+  @Test
   public void update_both_name_and_description() {
     insertDefaultGroupOnDefaultOrganization();
     GroupDto group = db.users().insertGroup();
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UsersActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UsersActionTest.java
index cfce3877ed3..554a1ba45fb 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UsersActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/usergroups/ws/UsersActionTest.java
@@ -22,6 +22,8 @@ package org.sonar.server.usergroups.ws;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
+import org.sonar.api.server.ws.Change;
+import org.sonar.api.server.ws.WebService.Action;
 import org.sonar.api.server.ws.WebService.Param;
 import org.sonar.api.server.ws.WebService.SelectionMode;
 import org.sonar.api.utils.System2;
@@ -38,6 +40,7 @@ import org.sonar.server.ws.TestRequest;
 import org.sonar.server.ws.WsActionTester;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.db.permission.OrganizationPermission.ADMINISTER;
 import static org.sonar.db.user.UserTesting.newUserDto;
 import static org.sonar.server.usergroups.ws.GroupWsSupport.PARAM_GROUP_ID;
@@ -56,6 +59,17 @@ public class UsersActionTest {
     new UsersAction(db.getDbClient(), userSession, new GroupWsSupport(db.getDbClient(), defaultOrganizationProvider, new DefaultGroupFinder(db.getDbClient()))));
 
   @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(false);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription).containsOnly(
+      tuple("8.4", "Parameter 'id' is deprecated. Format changes from integer to string. Use 'name' instead."));
+  }
+
+  @Test
   public void fail_if_unknown_group_uuid() {
     loginAsAdminOnDefaultOrganization();