SONAR-13436 Update Web API docs - custom_measures

server/sonar-webserver-webapi/src/main/java/org/sonar/server/measure/custom/ws/CreateAction.java

@@ -20,6 +20,7 @@
 package org.sonar.server.measure.custom.ws;
 
 import org.sonar.api.resources.Scopes;
+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;
@@ -37,11 +38,12 @@ import org.sonar.server.user.UserSession;
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkState;
 import static java.util.Objects.requireNonNull;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_01;
 import static org.sonar.server.component.ComponentFinder.ParamNames.PROJECT_ID_AND_KEY;
+import static org.sonar.server.exceptions.BadRequestException.checkRequest;
 import static org.sonar.server.measure.custom.ws.CustomMeasureValidator.checkPermissions;
 import static org.sonar.server.measure.custom.ws.CustomMeasureValueDescription.measureValueDescription;
 import static org.sonar.server.ws.KeyExamples.KEY_PROJECT_EXAMPLE_001;
-import static org.sonar.server.exceptions.BadRequestException.checkRequest;
 
 public class CreateAction implements CustomMeasuresWsAction {
   public static final String ACTION = "create";
@@ -78,7 +80,9 @@ public class CreateAction implements CustomMeasuresWsAction {
       .setSince("5.2")
       .setDeprecatedSince("7.4")
       .setPost(true)
-      .setHandler(this);
+      .setHandler(this)
+      .setChangelog(
+        new Change("8.4", "Param 'metricId' data type changes from integer to string."));
 
     action.createParam(PARAM_PROJECT_ID)
       .setDescription("Project id")
@@ -90,7 +94,7 @@ public class CreateAction implements CustomMeasuresWsAction {
 
     action.createParam(PARAM_METRIC_ID)
       .setDescription("Metric uuid")
-      .setExampleValue("16");
+      .setExampleValue(UUID_EXAMPLE_01);
 
     action.createParam(PARAM_METRIC_KEY)
       .setDescription("Metric key")

server/sonar-webserver-webapi/src/main/java/org/sonar/server/measure/custom/ws/DeleteAction.java

@@ -19,10 +19,12 @@
  */
 package org.sonar.server.measure.custom.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;
 import org.sonar.api.web.UserRole;
+import org.sonar.core.util.Uuids;
 import org.sonar.db.DbClient;
 import org.sonar.db.DbSession;
 import org.sonar.db.component.ComponentDto;
@@ -51,11 +53,13 @@ public class DeleteAction implements CustomMeasuresWsAction {
       .setHandler(this)
       .setSince("5.2")
       .setDeprecatedSince("7.4")
-      .setDescription("Delete a custom measure.<br /> Requires 'Administer System' permission or 'Administer' permission on the project.");
+      .setDescription("Delete a custom measure.<br /> Requires 'Administer System' permission or 'Administer' permission on the project.")
+      .setChangelog(
+        new Change("8.4", "Param 'id' data type changes from integer to string."));
 
     action.createParam(PARAM_ID)
-      .setDescription("d")
-      .setExampleValue("AU-TpxcA-iU5OvuD2FL3")
+      .setDescription("id")
+      .setExampleValue(Uuids.UUID_EXAMPLE_01)
       .setRequired(true);
   }
 

server/sonar-webserver-webapi/src/main/java/org/sonar/server/measure/custom/ws/UpdateAction.java

@@ -20,11 +20,13 @@
 package org.sonar.server.measure.custom.ws;
 
 import javax.annotation.Nullable;
+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;
 import org.sonar.api.utils.System2;
 import org.sonar.api.utils.text.JsonWriter;
+import org.sonar.core.util.Uuids;
 import org.sonar.db.DbClient;
 import org.sonar.db.DbSession;
 import org.sonar.db.component.ComponentDto;
@@ -67,12 +69,14 @@ public class UpdateAction implements CustomMeasuresWsAction {
         "Requires 'Administer System' permission or 'Administer' permission on the project.")
       .setHandler(this)
       .setSince("5.2")
-      .setDeprecatedSince("7.4");
+      .setDeprecatedSince("7.4")
+      .setChangelog(
+        new Change("8.4", "Param 'id' data type changes from integer to string."));
 
     action.createParam(PARAM_ID)
       .setRequired(true)
       .setDescription("id")
-      .setExampleValue("AU-TpxcA-iU5OvuD2FL3");
+      .setExampleValue(Uuids.UUID_EXAMPLE_01);
 
     action.createParam(PARAM_VALUE)
       .setExampleValue("true")

server/sonar-webserver-webapi/src/main/resources/org/sonar/server/measure/custom/ws/example-metrics.json

@@ -1,7 +1,7 @@
 {
   "metrics": [
     {
-      "id": "23",
+      "id": "AU-Tpxb--iU5OvuD2FLy",
       "key": "team_size",
       "name": "Team size",
       "description": "Number of people in the team",
@@ -13,7 +13,7 @@
       "custom": true
     },
     {
-      "id": "2",
+      "id": "AU-Tpxb--iU5OvuD3FLz",
       "key": "uncovered_lines",
       "name": "Uncovered lines",
       "description": "Uncovered lines",

server/sonar-webserver-webapi/src/test/java/org/sonar/server/measure/custom/ws/CreateActionTest.java

@@ -23,6 +23,8 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.measures.Metric;
+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.component.ComponentDto;
@@ -69,6 +71,18 @@ public class CreateActionTest {
     new CreateAction(db.getDbClient(), userSession, System2.INSTANCE, new CustomMeasureValidator(newFullTypeValidations()),
       new CustomMeasureJsonWriter(new UserJsonWriter(userSession)), TestComponentFinder.from(db)));
 
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isEqualTo("7.4");
+    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", "Param 'metricId' data type changes from integer to string."));
+  }
+
   @Test
   public void create_boolean_custom_measure_in_db() {
     MetricDto metric = db.measures().insertMetric(m -> m.setUserManaged(true).setValueType(BOOL.name()));

server/sonar-webserver-webapi/src/test/java/org/sonar/server/measure/custom/ws/DeleteActionTest.java

@@ -22,6 +22,8 @@ package org.sonar.server.measure.custom.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.api.web.UserRole;
 import org.sonar.db.DbClient;
@@ -36,6 +38,7 @@ import org.sonar.server.ws.WsActionTester;
 
 import static java.lang.String.valueOf;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.sonar.db.measure.custom.CustomMeasureTesting.newCustomMeasureDto;
 import static org.sonar.server.measure.custom.ws.DeleteAction.PARAM_ID;
 
@@ -51,7 +54,19 @@ public class DeleteActionTest {
   private DbClient dbClient = db.getDbClient();
   private final DbSession dbSession = db.getSession();
   private DeleteAction underTest = new DeleteAction(dbClient, userSession);
-  private WsActionTester tester = new WsActionTester(underTest);
+  private WsActionTester ws = new WsActionTester(underTest);
+
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isEqualTo("7.4");
+    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", "Param 'id' data type changes from integer to string."));
+  }
 
   @Test
   public void project_administrator_can_delete_custom_measures() {
@@ -59,7 +74,7 @@ public class DeleteActionTest {
     userSession.logIn().addProjectPermission(UserRole.ADMIN, project);
     String id = insertCustomMeasure(project);
 
-    tester.newRequest().setParam(PARAM_ID, valueOf(id)).execute();
+    ws.newRequest().setParam(PARAM_ID, valueOf(id)).execute();
 
     assertThat(dbClient.customMeasureDao().selectByUuid(dbSession, id)).isEmpty();
   }
@@ -69,7 +84,7 @@ public class DeleteActionTest {
     expectedException.expect(IllegalArgumentException.class);
     expectedException.expectMessage("Custom measure with id '42' does not exist");
 
-    tester.newRequest().setParam(PARAM_ID, "42").execute();
+    ws.newRequest().setParam(PARAM_ID, "42").execute();
   }
 
   @Test
@@ -79,7 +94,7 @@ public class DeleteActionTest {
     userSession.logIn().setNonSystemAdministrator();
 
     expectedException.expect(ForbiddenException.class);
-    tester.newRequest().setParam(PARAM_ID, valueOf(uuid)).execute();
+    ws.newRequest().setParam(PARAM_ID, valueOf(uuid)).execute();
   }
 
   @Test
@@ -89,7 +104,7 @@ public class DeleteActionTest {
     userSession.anonymous();
 
     expectedException.expect(UnauthorizedException.class);
-    tester.newRequest().setParam(PARAM_ID, valueOf(uuid)).execute();
+    ws.newRequest().setParam(PARAM_ID, valueOf(uuid)).execute();
   }
 
   private String insertCustomMeasure(ComponentDto component) {

server/sonar-webserver-webapi/src/test/java/org/sonar/server/measure/custom/ws/UpdateActionTest.java

@@ -22,8 +22,10 @@ package org.sonar.server.measure.custom.ws;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
-import org.sonar.api.utils.System2;
 import org.sonar.api.impl.utils.TestSystem2;
+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.component.ComponentDto;
 import org.sonar.db.measure.custom.CustomMeasureDto;
@@ -66,6 +68,18 @@ public class UpdateActionTest {
   private WsActionTester ws = new WsActionTester(new UpdateAction(db.getDbClient(), userSession, system, new CustomMeasureValidator(newFullTypeValidations()),
     new CustomMeasureJsonWriter(new UserJsonWriter(userSession))));
 
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isEqualTo("7.4");
+    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", "Param 'id' data type changes from integer to string."));
+  }
+
   @Test
   public void update_text_value_and_description_in_db() {
     ComponentDto project = db.components().insertPrivateProject();