SONAR-13436 Update Web API docs - metrics

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

@@ -21,6 +21,7 @@ package org.sonar.server.metric.ws;
 
 import com.google.common.collect.Lists;
 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;
@@ -30,6 +31,10 @@ import org.sonar.db.metric.MetricDto;
 import org.sonar.server.user.UserSession;
 
 import static com.google.common.base.Preconditions.checkArgument;
+import static java.lang.String.join;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_01;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_02;
+import static org.sonar.core.util.Uuids.UUID_EXAMPLE_03;
 
 public class DeleteAction implements MetricsWsAction {
   private static final String PARAM_IDS = "ids";
@@ -52,11 +57,13 @@ public class DeleteAction implements MetricsWsAction {
       .setHandler(this)
       .setSince("5.2")
       .setDeprecatedSince("7.7")
-      .setPost(true);
+      .setPost(true)
+      .setChangelog(
+        new Change("8.4", "Parameter 'ids' format changes from integer to string."));
 
     action.createParam(PARAM_IDS)
       .setDescription("Metrics uuids to delete.")
-      .setExampleValue("5, 23, 42");
+      .setExampleValue(join(", ", UUID_EXAMPLE_01, UUID_EXAMPLE_02, UUID_EXAMPLE_03));
 
     action.createParam(PARAM_KEYS)
       .setDescription("Metrics keys to delete")

server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/SearchAction.java

@@ -62,9 +62,9 @@ public class SearchAction implements MetricsWsAction {
       .setDescription("Search for metrics")
       .setResponseExample(getClass().getResource("example-search.json"))
       .addPagingParams(100, MAX_LIMIT)
-
-      .setChangelog(new Change("7.7", "The response field 'custom' is deprecated"))
-      .setChangelog(new Change("8.3", "The response field 'id' is deprecated"))
+      .setChangelog(
+        new Change("8.4", "Field 'id' in the response is deprecated"),
+        new Change("7.7", "Field 'custom' in the response is deprecated"))
       .setHandler(this);
 
     action.createFieldsParam(MetricJsonWriter.OPTIONAL_FIELDS)

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

@@ -22,10 +22,12 @@ package org.sonar.server.metric.ws;
 import java.util.List;
 import javax.annotation.Nullable;
 import org.sonar.api.measures.Metric;
+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.text.JsonWriter;
+import org.sonar.core.util.Uuids;
 import org.sonar.db.DbClient;
 import org.sonar.db.DbSession;
 import org.sonar.db.measure.custom.CustomMeasureDto;
@@ -71,12 +73,14 @@ public class UpdateAction implements MetricsWsAction {
         "Requires 'Administer System' permission.")
       .setSince("5.2")
       .setDeprecatedSince("7.7")
-      .setHandler(this);
+      .setHandler(this)
+      .setChangelog(
+        new Change("8.4", "Parameter 'id' format changes from integer to string."));
 
     action.createParam(PARAM_ID)
       .setRequired(true)
       .setDescription("UUID of the custom metric to update")
-      .setExampleValue("42");
+      .setExampleValue(Uuids.UUID_EXAMPLE_01);
 
     action.createParam(PARAM_KEY)
       .setDescription("Key")

server/sonar-webserver-webapi/src/main/resources/org/sonar/server/metric/ws/example-search.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-TpxcB-iU5OvuD2FL7",
       "key": "uncovered_lines",
       "name": "Uncovered lines",
       "description": "Uncovered lines",

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

@@ -23,6 +23,8 @@ import java.util.List;
 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.DbClient;
 import org.sonar.db.DbTester;
@@ -39,6 +41,7 @@ import org.sonar.server.ws.WsActionTester;
 
 import static java.util.Arrays.asList;
 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.db.metric.MetricTesting.newMetricDto;
 
@@ -54,6 +57,19 @@ public class DeleteActionTest {
   private DbClient dbClient = db.getDbClient();
   private WsActionTester ws = new WsActionTester(new DeleteAction(dbClient, userSessionRule));
 
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isEqualTo("7.7");
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription)
+      .containsExactly(
+        tuple("8.4", "Parameter 'ids' format changes from integer to string."));
+  }
+
   @Test
   public void delete_by_keys() {
     loggedAsSystemAdministrator();

server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/SearchActionTest.java

@@ -22,6 +22,8 @@ package org.sonar.server.metric.ws;
 import org.apache.commons.lang.StringUtils;
 import org.junit.Rule;
 import org.junit.Test;
+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.utils.System2;
 import org.sonar.db.DbClient;
@@ -32,6 +34,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.db.metric.MetricTesting.newMetricDto;
 import static org.sonar.server.metric.ws.SearchAction.PARAM_IS_CUSTOM;
 
@@ -43,13 +46,27 @@ public class SearchActionTest {
   private DbClient dbClient = db.getDbClient();
   private final DbSession dbSession = db.getSession();
   private SearchAction underTest = new SearchAction(dbClient);
-  private WsActionTester tester = new WsActionTester(underTest);
+  private WsActionTester ws = new WsActionTester(underTest);
+
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isNull();
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(false);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription)
+      .containsExactlyInAnyOrder(
+        tuple("8.4", "Field 'id' in the response is deprecated"),
+        tuple("7.7", "Field 'custom' in the response is deprecated"));
+  }
 
   @Test
   public void search_metrics_in_database() {
     insertNewCustomMetric("1", "2", "3");
 
-    TestResponse result = tester.newRequest().execute();
+    TestResponse result = ws.newRequest().execute();
 
     result.assertJson(getClass(), "search_metrics.json");
   }
@@ -58,9 +75,9 @@ public class SearchActionTest {
   public void search_metrics_ordered_by_name_case_insensitive() {
     insertNewCustomMetric("3", "1", "2");
 
-    String firstResult = tester.newRequest().setParam(Param.PAGE, "1").setParam(Param.PAGE_SIZE, "1").execute().getInput();
-    String secondResult = tester.newRequest().setParam(Param.PAGE, "2").setParam(Param.PAGE_SIZE, "1").execute().getInput();
-    String thirdResult = tester.newRequest().setParam(Param.PAGE, "3").setParam(Param.PAGE_SIZE, "1").execute().getInput();
+    String firstResult = ws.newRequest().setParam(Param.PAGE, "1").setParam(Param.PAGE_SIZE, "1").execute().getInput();
+    String secondResult = ws.newRequest().setParam(Param.PAGE, "2").setParam(Param.PAGE_SIZE, "1").execute().getInput();
+    String thirdResult = ws.newRequest().setParam(Param.PAGE, "3").setParam(Param.PAGE_SIZE, "1").execute().getInput();
 
     assertThat(firstResult).contains("custom-key-1").doesNotContain("custom-key-2").doesNotContain("custom-key-3");
     assertThat(secondResult).contains("custom-key-2").doesNotContain("custom-key-1").doesNotContain("custom-key-3");
@@ -71,7 +88,7 @@ public class SearchActionTest {
   public void search_metrics_with_pagination() {
     insertNewCustomMetric("1", "2", "3", "4", "5", "6", "7", "8", "9", "10");
 
-    TestResponse result = tester.newRequest()
+    TestResponse result = ws.newRequest()
       .setParam(Param.PAGE, "3")
       .setParam(Param.PAGE_SIZE, "4")
       .execute();
@@ -84,7 +101,7 @@ public class SearchActionTest {
     insertNewCustomMetric("1", "2");
     insertNewNonCustomMetric("3");
 
-    String result = tester.newRequest()
+    String result = ws.newRequest()
       .setParam(PARAM_IS_CUSTOM, "true").execute().getInput();
 
     assertThat(result).contains("custom-key-1", "custom-key-2")
@@ -96,7 +113,7 @@ public class SearchActionTest {
     insertNewCustomMetric("1", "2");
     insertNewNonCustomMetric("3");
 
-    String result = tester.newRequest()
+    String result = ws.newRequest()
       .setParam(PARAM_IS_CUSTOM, "false").execute().getInput();
 
     assertThat(result).doesNotContain("custom-key-1")
@@ -108,7 +125,7 @@ public class SearchActionTest {
   public void list_metric_with_chosen_fields() {
     insertNewCustomMetric("1");
 
-    String result = tester.newRequest().setParam(Param.FIELDS, "name").execute().getInput();
+    String result = ws.newRequest().setParam(Param.FIELDS, "name").execute().getInput();
 
     assertThat(result).contains("id", "key", "name", "type")
       .doesNotContain("domain")

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

@@ -24,6 +24,8 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.measures.Metric.ValueType;
+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.DbClient;
 import org.sonar.db.DbSession;
@@ -37,6 +39,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.db.measure.custom.CustomMeasureTesting.newCustomMeasureDto;
 import static org.sonar.server.metric.ws.UpdateAction.PARAM_DESCRIPTION;
 import static org.sonar.server.metric.ws.UpdateAction.PARAM_DOMAIN;
@@ -64,18 +67,31 @@ public class UpdateActionTest {
   private DbClient dbClient = db.getDbClient();
   private final DbSession dbSession = db.getSession();
   private UpdateAction underTest = new UpdateAction(dbClient, userSessionRule);
-  private WsActionTester tester = new WsActionTester(underTest);
+  private WsActionTester ws = new WsActionTester(underTest);
 
   @Before
   public void setUp() {
     userSessionRule.logIn().setSystemAdministrator();
   }
 
+  @Test
+  public void verify_definition() {
+    Action wsDef = ws.getDef();
+
+    assertThat(wsDef.deprecatedSince()).isEqualTo("7.7");
+    assertThat(wsDef.isInternal()).isEqualTo(false);
+    assertThat(wsDef.since()).isEqualTo("5.2");
+    assertThat(wsDef.isPost()).isEqualTo(true);
+    assertThat(wsDef.changelog()).extracting(Change::getVersion, Change::getDescription)
+      .containsExactly(
+        tuple("8.4", "Parameter 'id' format changes from integer to string."));
+  }
+
   @Test
   public void update_all_fields() {
     String uuid = insertMetric(newDefaultMetric());
 
-    tester.newRequest()
+    ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_KEY, "another-key")
       .setParam(PARAM_NAME, "another-name")
@@ -99,7 +115,7 @@ public class UpdateActionTest {
     dbClient.customMeasureDao().insert(dbSession, newCustomMeasureDto().setMetricUuid(uuid));
     dbSession.commit();
 
-    tester.newRequest()
+    ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_DESCRIPTION, "another-description")
       .execute();
@@ -117,7 +133,7 @@ public class UpdateActionTest {
   public void update_return_the_full_object_with_id() {
     String uuid = insertMetric(newDefaultMetric().setDescription("another-description"));
 
-    TestResponse requestResult = tester.newRequest()
+    TestResponse requestResult = ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_DESCRIPTION, DEFAULT_DESCRIPTION)
       .execute();
@@ -134,7 +150,7 @@ public class UpdateActionTest {
     insertMetric(newDefaultMetric().setKey("metric-key"));
     String uuid = insertMetric(newDefaultMetric().setUuid("another-uuid").setKey("another-key"));
 
-    tester.newRequest()
+    ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_KEY, "metric-key")
       .execute();
@@ -144,7 +160,7 @@ public class UpdateActionTest {
   public void fail_when_metric_not_in_db() {
     expectedException.expect(ServerException.class);
 
-    tester.newRequest().setParam(PARAM_ID, "42").execute();
+    ws.newRequest().setParam(PARAM_ID, "42").execute();
   }
 
   @Test
@@ -152,7 +168,7 @@ public class UpdateActionTest {
     expectedException.expect(ServerException.class);
     String uuid = insertMetric(newDefaultMetric().setEnabled(false));
 
-    tester.newRequest().setParam(PARAM_ID, uuid).execute();
+    ws.newRequest().setParam(PARAM_ID, uuid).execute();
   }
 
   @Test
@@ -160,7 +176,7 @@ public class UpdateActionTest {
     expectedException.expect(ServerException.class);
     String uuid = insertMetric(newDefaultMetric().setUserManaged(false));
 
-    tester.newRequest().setParam(PARAM_ID, uuid).execute();
+    ws.newRequest().setParam(PARAM_ID, uuid).execute();
   }
 
   @Test
@@ -170,7 +186,7 @@ public class UpdateActionTest {
     dbClient.customMeasureDao().insert(dbSession, newCustomMeasureDto().setMetricUuid(uuid));
     dbSession.commit();
 
-    tester.newRequest()
+    ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_TYPE, ValueType.BOOL.name())
       .execute();
@@ -180,7 +196,7 @@ public class UpdateActionTest {
   public void fail_when_no_id() {
     expectedException.expect(IllegalArgumentException.class);
 
-    tester.newRequest().execute();
+    ws.newRequest().execute();
   }
 
   @Test
@@ -190,7 +206,7 @@ public class UpdateActionTest {
     expectedException.expect(ForbiddenException.class);
     expectedException.expectMessage("Insufficient privileges");
 
-    tester.newRequest().execute();
+    ws.newRequest().execute();
   }
 
   @Test
@@ -200,7 +216,7 @@ public class UpdateActionTest {
     expectedException.expect(UnauthorizedException.class);
     expectedException.expectMessage("Authentication is required");
 
-    tester.newRequest().execute();
+    ws.newRequest().execute();
   }
 
   @Test
@@ -212,7 +228,7 @@ public class UpdateActionTest {
     expectedException.expect(IllegalArgumentException.class);
     expectedException.expectMessage("Malformed metric key 'not well formatted key'. Allowed characters are alphanumeric, '-', '_', with at least one non-digit.");
 
-    tester.newRequest()
+    ws.newRequest()
       .setParam(PARAM_ID, uuid)
       .setParam(PARAM_KEY, "not well formatted key")
       .execute();