From d67d7addd11df8cc7351273a3e60d098a20a1d55 Mon Sep 17 00:00:00 2001 From: Simon Brandhof Date: Fri, 2 Oct 2015 11:40:50 +0200 Subject: [PATCH] Improve documentation of web services api/ce --- .../computation/ws/ActivityWsAction.java | 7 ++++-- .../computation/ws/CancelAllWsAction.java | 3 ++- .../server/computation/ws/CancelWsAction.java | 3 ++- .../computation/ws/ComponentWsAction.java | 4 ++- .../server/computation/ws/IsQueueEmptyWs.java | 2 +- .../server/computation/ws/LogsWsAction.java | 3 ++- .../server/computation/ws/QueueWsAction.java | 5 ++-- .../server/computation/ws/SubmitWsAction.java | 4 ++- .../server/computation/ws/TaskWsAction.java | 2 ++ .../server/computation/ws/task-example.json | 15 +++++++++++ .../computation/ws/ActivityWsActionTest.java | 11 ++++++++ .../computation/ws/TaskWsActionTest.java | 25 ++++++++++++++++--- 12 files changed, 70 insertions(+), 14 deletions(-) create mode 100644 server/sonar-server/src/main/resources/org/sonar/server/computation/ws/task-example.json diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ActivityWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ActivityWsAction.java index 4d0dd94271e..f34dfd063d3 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ActivityWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ActivityWsAction.java @@ -75,13 +75,16 @@ public class ActivityWsAction implements CeWsAction { public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("activity") .setInternal(true) + .setDescription(format("Search for past task executions. Requires the system administration permission, " + + "or project administration permission if %s is set.", PARAM_COMPONENT_UUID)) .setResponseExample(getClass().getResource("activity-example.json")) - .setHandler(this); + .setHandler(this) + .setSince("5.2"); action.createParam(PARAM_COMPONENT_UUID) .setDescription("Optional id of the component (project) to filter on") .setExampleValue(Uuids.UUID_EXAMPLE_03); action.createParam(PARAM_COMPONENT_QUERY) - .setDescription(format("Optional search by component name or key. Must not be set together with %s", PARAM_COMPONENT_UUID)) + .setDescription(format("Optional search by component name or key. Must not be set together with %s.", PARAM_COMPONENT_UUID)) .setExampleValue("Apache"); action.createParam(PARAM_STATUS) .setDescription("Optional filter on task status") diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelAllWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelAllWsAction.java index 23150d2ba0f..6b7e4fa8f26 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelAllWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelAllWsAction.java @@ -39,9 +39,10 @@ public class CancelAllWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { controller.createAction("cancel_all") - .setDescription("Cancels all pending task. Requires system administration permission.") + .setDescription("Cancels all pending tasks. Requires system administration permission. In-progress tasks are not canceled.") .setInternal(true) .setPost(true) + .setSince("5.2") .setHandler(this); } diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelWsAction.java index 3b39b2a7e85..243bc107801 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/CancelWsAction.java @@ -42,9 +42,10 @@ public class CancelWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("cancel") - .setDescription("Cancels a pending task. Requires system administration permission.") + .setDescription("Cancels a pending task. Requires system administration permission. In-progress tasks can not be canceled.") .setInternal(true) .setPost(true) + .setSince("5.2") .setHandler(this); action diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ComponentWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ComponentWsAction.java index f84a9b541a5..9bc310675ec 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ComponentWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/ComponentWsAction.java @@ -53,8 +53,10 @@ public class ComponentWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("component") - .setDescription("Get the pending and last executed tasks of a given component (usually a project)") + .setDescription("Get the pending tasks, in-progress tasks and the last executed task of a given component " + + "(usually a project). Requires the administration permission on the component.") .setInternal(true) + .setSince("5.2") .setResponseExample(getClass().getResource("component-example.json")) .setHandler(this); diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/IsQueueEmptyWs.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/IsQueueEmptyWs.java index a789d61c94a..5856e0f7fd5 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/IsQueueEmptyWs.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/IsQueueEmptyWs.java @@ -44,7 +44,7 @@ public class IsQueueEmptyWs implements WebService { public void define(Context context) { NewController controller = context .createController(API_ENDPOINT) - .setDescription("Analysis reports processed"); + .setDescription("For internal testing - do not use"); action.define(controller); controller.done(); } diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/LogsWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/LogsWsAction.java index 1d654e9402e..f3fc4cc302f 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/LogsWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/LogsWsAction.java @@ -58,9 +58,10 @@ public class LogsWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction(ACTION) - .setDescription("Logs of a task. Returns HTTP code 404 if task does not " + + .setDescription("Logs of a task. Format of response is plain text. HTTP code 404 is returned if the task does not " + "exist or if logs are not available. Requires system administration permission.") .setInternal(true) + .setSince("5.2") .setHandler(this); action diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/QueueWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/QueueWsAction.java index efb96a839ba..2a1a63d7443 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/QueueWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/QueueWsAction.java @@ -50,8 +50,9 @@ public class QueueWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("queue") - .setDescription("Gets the tasks of the Compute Engine queue") + .setDescription("Gets the pending and in-progress tasks. Requires system administration permission.") .setInternal(true) + .setSince("5.2") .setResponseExample(getClass().getResource("queue-example.json")) .setHandler(this); @@ -74,7 +75,7 @@ public class QueueWsAction implements CeWsAction { if (userSession.hasGlobalPermission(GlobalPermissions.SYSTEM_ADMIN) || userSession.hasComponentUuidPermission(UserRole.ADMIN, componentUuid)) { dtos = dbClient.ceQueueDao().selectByComponentUuid(dbSession, componentUuid); } else { - throw new ForbiddenException("Requires administration permission"); + throw new ForbiddenException("Requires system administration permission"); } } diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/SubmitWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/SubmitWsAction.java index 64c1f2daf13..23de0b32722 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/SubmitWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/SubmitWsAction.java @@ -45,9 +45,11 @@ public class SubmitWsAction implements CeWsAction { @Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("submit") - .setDescription("Submit an analysis report to the queue of Compute Engine. Report is processed asynchronously.") + .setDescription("Submits a scanner report to the queue. Report is processed asynchronously. Requires analysis permission. " + + "If the project does not exist, then the provisioning permission is also required.") .setPost(true) .setInternal(true) + .setSince("5.2") .setHandler(this) .setResponseExample(getClass().getResource("submit-example.json")); diff --git a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/TaskWsAction.java b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/TaskWsAction.java index b79bc416424..0d63ab8c0cd 100644 --- a/server/sonar-server/src/main/java/org/sonar/server/computation/ws/TaskWsAction.java +++ b/server/sonar-server/src/main/java/org/sonar/server/computation/ws/TaskWsAction.java @@ -54,6 +54,8 @@ public class TaskWsAction implements CeWsAction { WebService.NewAction action = controller.createAction(ACTION) .setDescription("Task information") .setInternal(true) + .setResponseExample(getClass().getResource("task-example.json")) + .setSince("5.2") .setHandler(this); action diff --git a/server/sonar-server/src/main/resources/org/sonar/server/computation/ws/task-example.json b/server/sonar-server/src/main/resources/org/sonar/server/computation/ws/task-example.json new file mode 100644 index 00000000000..3b49ca0b3b3 --- /dev/null +++ b/server/sonar-server/src/main/resources/org/sonar/server/computation/ws/task-example.json @@ -0,0 +1,15 @@ +{ + "task": { + "id": "AVAn5RKqYwETbXvgas-I", + "type": "REPORT", + "componentId": "AVAn5RJmYwETbXvgas-H", + "componentKey": "project_1", + "componentName": "Project One", + "status": "SUCCESS", + "submittedAt": "2015-10-02T11:32:15+0200", + "startedAt": "2015-10-02T11:32:16+0200", + "executedAt": "2015-10-02T11:32:22+0200", + "executionTimeMs": 5286, + "logs": true + } +} diff --git a/server/sonar-server/src/test/java/org/sonar/server/computation/ws/ActivityWsActionTest.java b/server/sonar-server/src/test/java/org/sonar/server/computation/ws/ActivityWsActionTest.java index 7e856fc5ed2..18f0f550ca1 100644 --- a/server/sonar-server/src/test/java/org/sonar/server/computation/ws/ActivityWsActionTest.java +++ b/server/sonar-server/src/test/java/org/sonar/server/computation/ws/ActivityWsActionTest.java @@ -44,6 +44,7 @@ import org.sonar.server.plugins.MimeTypes; import org.sonar.server.tester.UserSessionRule; import org.sonar.server.ws.TestResponse; import org.sonar.server.ws.WsActionTester; +import org.sonar.test.JsonAssert; import org.sonarqube.ws.WsCe; import static java.util.Arrays.asList; @@ -218,6 +219,16 @@ public class ActivityWsActionTest { .execute(); } + @Test + public void support_json_response() { + userSession.setGlobalPermissions(UserRole.ADMIN); + TestResponse wsResponse = tester.newRequest() + .setMediaType(MimeTypes.JSON) + .execute(); + + JsonAssert.assertJson(wsResponse.getInput()).isSimilarTo("{\"tasks\":[]}"); + } + private CeActivityDto insert(String taskUuid, String componentUuid, CeActivityDto.Status status) { CeQueueDto queueDto = new CeQueueDto(); queueDto.setTaskType(CeTaskTypes.REPORT); diff --git a/server/sonar-server/src/test/java/org/sonar/server/computation/ws/TaskWsActionTest.java b/server/sonar-server/src/test/java/org/sonar/server/computation/ws/TaskWsActionTest.java index 31724c81ee5..5f0e1d69292 100644 --- a/server/sonar-server/src/test/java/org/sonar/server/computation/ws/TaskWsActionTest.java +++ b/server/sonar-server/src/test/java/org/sonar/server/computation/ws/TaskWsActionTest.java @@ -39,6 +39,7 @@ import org.sonar.server.plugins.MimeTypes; import org.sonar.server.tester.UserSessionRule; import org.sonar.server.ws.TestResponse; import org.sonar.server.ws.WsActionTester; +import org.sonar.test.JsonAssert; import org.sonarqube.ws.WsCe; import static org.assertj.core.api.Assertions.assertThat; @@ -78,14 +79,13 @@ public class TaskWsActionTest { queueDto.setStatus(CeQueueDto.Status.PENDING); queueDto.setSubmitterLogin("john"); dbTester.getDbClient().ceQueueDao().insert(dbTester.getSession(), queueDto); - dbTester.getSession().commit(); + dbTester.commit(); TestResponse wsResponse = tester.newRequest() .setMediaType(MimeTypes.PROTOBUF) .setParam("id", "TASK_1") .execute(); - // verify the protobuf response WsCe.TaskResponse taskResponse = Protobuf.read(wsResponse.getInputStream(), WsCe.TaskResponse.PARSER); assertThat(taskResponse.getTask().getId()).isEqualTo("TASK_1"); assertThat(taskResponse.getTask().getStatus()).isEqualTo(WsCe.TaskStatus.PENDING); @@ -112,14 +112,13 @@ public class TaskWsActionTest { activityDto.setStatus(CeActivityDto.Status.FAILED); activityDto.setExecutionTimeMs(500L); dbTester.getDbClient().ceActivityDao().insert(dbTester.getSession(), activityDto); - dbTester.getSession().commit(); + dbTester.commit(); TestResponse wsResponse = tester.newRequest() .setMediaType(MimeTypes.PROTOBUF) .setParam("id", "TASK_1") .execute(); - // verify the protobuf response WsCe.TaskResponse taskResponse = Protobuf.read(wsResponse.getInputStream(), WsCe.TaskResponse.PARSER); assertThat(taskResponse.getTask().getId()).isEqualTo("TASK_1"); assertThat(taskResponse.getTask().getStatus()).isEqualTo(WsCe.TaskStatus.FAILED); @@ -138,4 +137,22 @@ public class TaskWsActionTest { .setParam("id", "DOES_NOT_EXIST") .execute(); } + + @Test + public void support_json_response() { + CeQueueDto queueDto = new CeQueueDto(); + queueDto.setTaskType("fake"); + queueDto.setUuid("TASK_1"); + queueDto.setStatus(CeQueueDto.Status.PENDING); + dbTester.getDbClient().ceQueueDao().insert(dbTester.getSession(), queueDto); + dbTester.commit(); + + userSession.setGlobalPermissions(UserRole.ADMIN); + TestResponse wsResponse = tester.newRequest() + .setMediaType(MimeTypes.JSON) + .setParam("id", "TASK_1") + .execute(); + + JsonAssert.assertJson(wsResponse.getInput()).isSimilarTo("{\"task\":{}}"); + } } -- 2.39.5