Improve documentation of web services api/ce

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 4d0dd94271e4ef99064a39b7e12e24dc8a0a6492..f34dfd063d3fa2dd409436e17c987f3f4d0577c4 100644 (file)
--- 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 23150d2ba0f434280e69cc383d7f06a0d65b2fb7..6b7e4fa8f260e1098dedabc56351cda9398825cb 100644 (file)
--- 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 3b39b2a7e85c7fe3529802cc1e4ba0a0857a6168..243bc1078018f7e81aeb8fa211ab92c1737fb1f0 100644 (file)
--- 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 f84a9b541a5ed80fd0253a0cf0a23d3773e9c001..9bc310675ec6b4286b5285137daf5c49f22f8981 100644 (file)
--- 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 a789d61c94a806192ccdff4b275358b206f67dc0..5856e0f7fd56c7d6a0d340b3dd3fccfec7c8775b 100644 (file)
--- 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 1d654e9402e92081d4f786243a2a7e57e12d4050..f3fc4cc302ff729b1ec840fe36a93a95dcb1fb3c 100644 (file)
--- 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 efb96a839baac0f6a2ade9fe127d349981fe3811..2a1a63d7443981b145bd2ddd2647a22ed980da00 100644 (file)
--- 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 64c1f2daf13b52e8fe226a1dbe35b4e92ff18ad0..23de0b3272245d8d794a466679b042fa7dc024f4 100644 (file)
--- 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 b79bc416424985c7026f2363fd9d54a1cde186c7..0d63ab8c0cd77abf2572804ef79136468eddbd55 100644 (file)
--- 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 (file)
index 0000000..3b49ca0
--- /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 7e856fc5ed2de3d2670ed9515a76404ef7cacc62..18f0f550ca1642ec2f8b6c25d3deeca2d3ce40f6 100644 (file)
--- 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 31724c81ee535eabcc2c288994042cbab212c411..5f0e1d692926284e1f3921bfc5a46b82fcc4a93b 100644 (file)
--- 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\":{}}");
+  }
 }