From f4eac316acadfd8851f4d498bf411bea99899685 Mon Sep 17 00:00:00 2001 From: Jacek Date: Wed, 20 May 2020 09:48:59 +0200 Subject: [PATCH] SONAR-13436 Update Web API docs - metrics --- .../sonar/server/metric/ws/DeleteAction.java | 11 ++++- .../sonar/server/metric/ws/SearchAction.java | 6 +-- .../sonar/server/metric/ws/UpdateAction.java | 8 +++- .../server/metric/ws/example-search.json | 4 +- .../server/metric/ws/DeleteActionTest.java | 16 +++++++ .../server/metric/ws/SearchActionTest.java | 35 ++++++++++++---- .../server/metric/ws/UpdateActionTest.java | 42 +++++++++++++------ 7 files changed, 91 insertions(+), 31 deletions(-) diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/DeleteAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/DeleteAction.java index 1ba3204019d..e8d9019c5a8 100644 --- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/DeleteAction.java +++ b/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") diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/SearchAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/SearchAction.java index c47c36bcf85..0a0e6eeb32a 100644 --- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/SearchAction.java +++ b/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) diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/UpdateAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/UpdateAction.java index bbaa5b790f0..4076bc5702e 100644 --- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/metric/ws/UpdateAction.java +++ b/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") diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/metric/ws/example-search.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/metric/ws/example-search.json index 608ba77048c..a10a1d76c86 100644 --- a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/metric/ws/example-search.json +++ b/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", diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/DeleteActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/DeleteActionTest.java index 9ef27363162..6c29327d0e4 100644 --- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/DeleteActionTest.java +++ b/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(); diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/SearchActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/SearchActionTest.java index 49e9477fc1f..f759201fb13 100644 --- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/SearchActionTest.java +++ b/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") diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/UpdateActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/UpdateActionTest.java index 0b9ce49f186..38b9d648765 100644 --- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/metric/ws/UpdateActionTest.java +++ b/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(); -- 2.39.5