SONAR-5111 Complete api/projects WS documentations

sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java

@@ -472,6 +472,13 @@ public interface WebService extends ServerExtension {
       return setPossibleValues(values == null ? (Collection) null : Arrays.asList(values));
     }
 
+    /**
+     * @since 4.4
+     */
+    public NewParam setBooleanPossibleValues() {
+      return setPossibleValues("true", "false");
+    }
+
     /**
      * Exhaustive list of possible values when it makes sense, for example
      * list of severities.

sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java

@@ -20,6 +20,7 @@
 
 package org.sonar.server.component.ws;
 
+import com.google.common.io.Resources;
 import org.sonar.api.server.ws.RailsHandler;
 import org.sonar.api.server.ws.WebService;
 
@@ -28,17 +29,61 @@ public class ProjectsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/projects")
-      .setSince("4.0")
+      .setSince("2.10")
       .setDescription("Projects management");
 
+    defineIndexAction(controller);
     defineCreateAction(controller);
+    defineDestroyAction(controller);
 
     controller.done();
   }
 
+  private void defineIndexAction(NewController controller) {
+    WebService.NewAction action = controller.createAction("index")
+      .setDescription("Search for projects")
+      .setSince("2.10")
+      .setPost(true)
+      .setHandler(RailsHandler.INSTANCE)
+      .setResponseExample(Resources.getResource(this.getClass(), "example-index.json"));
+
+    action.createParam("key")
+      .setDescription("id or key of the project")
+      .setExampleValue("org.codehaus.sonar:sonar");
+
+    action.createParam("search")
+      .setDescription("substring of project name, case insensitive")
+      .setExampleValue("Sonar");
+
+    action.createParam("desc")
+      .setDescription("Load project description")
+      .setDefaultValue("true")
+      .setBooleanPossibleValues();
+
+    action.createParam("subprojects")
+      .setDescription("Load sub-projects. Ignored if the parameter key is set")
+      .setDefaultValue("false")
+      .setBooleanPossibleValues();
+
+    action.createParam("views")
+      .setDescription("Load views and sub-views. Ignored if the parameter key is set")
+      .setDefaultValue("false")
+      .setBooleanPossibleValues();
+
+    action.createParam("libs")
+      .setDescription("Load libraries. Ignored if the parameter key is set")
+      .setDefaultValue("false")
+      .setBooleanPossibleValues();
+
+    action.createParam("versions")
+      .setDescription("Load version")
+      .setDefaultValue("false")
+      .setPossibleValues("true", "false", "last");
+  }
+
   private void defineCreateAction(NewController controller) {
     WebService.NewAction action = controller.createAction("create")
-      .setDescription("Provision a project. Requires Provision Projects permission.")
+      .setDescription("Provision a project. Requires Provision Projects permission")
       .setSince("4.0")
       .setPost(true)
       .setHandler(RailsHandler.INSTANCE);
@@ -54,4 +99,17 @@ public class ProjectsWs implements WebService {
       .setExampleValue("SonarQube");
   }
 
+  private void defineDestroyAction(NewController controller) {
+    WebService.NewAction action = controller.createAction("destroy")
+      .setDescription("Delete a project. Requires Administer System permission")
+      .setSince("2.11")
+      .setPost(true)
+      .setHandler(RailsHandler.INSTANCE);
+
+    action.createParam("id")
+      .setDescription("id or key of the resource (ie: component)")
+      .setRequired(true)
+      .setExampleValue("org.codehaus.sonar:sonar");
+  }
+
 }

sonar-server/src/main/java/org/sonar/server/component/ws/package-info.java

@@ -0,0 +1,24 @@
+/*
+ * SonarQube, open source software quality management tool.
+ * Copyright (C) 2008-2014 SonarSource
+ * mailto:contact AT sonarsource DOT com
+ *
+ * SonarQube is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * SonarQube is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+@ParametersAreNonnullByDefault
+package org.sonar.server.component.ws;
+
+import javax.annotation.ParametersAreNonnullByDefault;

sonar-server/src/main/java/org/sonar/server/qualitygate/ws/QGatesWs.java

@@ -121,7 +121,13 @@ public class QGatesWs implements WebService {
       .setExampleValue("blocker_violations");
 
     action.createParam(PARAM_OPERATOR)
-      .setDescription("Condition operator. EQ = equals, NE = is not, LT = is lower than, GT = is greater than")
+      .setDescription("Condition operator:<br/>" +
+        "<ul>" +
+        "<li>EQ = equals</li>" +
+        "<li>NE = is not</li>" +
+        "<li>LT = is lower than</li>" +
+        "<li>GT = is greater than</li>" +
+        "</ui>")
       .setExampleValue(QualityGateConditionDto.OPERATOR_EQUALS)
       .setPossibleValues(QualityGateConditionDto.ALL_OPERATORS);
 

sonar-server/src/main/resources/org/sonar/server/component/ws/example-index.json

@@ -0,0 +1,23 @@
+[
+  {
+    "id": "5035",
+    "k": "org.jenkins-ci.plugins:sonar",
+    "nm": "Jenkins Sonar Plugin",
+    "sc": "PRJ",
+    "qu": "TRK"
+  },
+  {
+    "id": "5146",
+    "k": "org.codehaus.sonar-plugins:sonar-ant-task",
+    "nm": "Sonar Ant Task",
+    "sc": "PRJ",
+    "qu": "TRK"
+  },
+  {
+    "id": "15964",
+    "k": "org.codehaus.sonar-plugins:sonar-build-breaker-plugin",
+    "nm": "Sonar Build Breaker Plugin",
+    "sc": "PRJ",
+    "qu": "TRK"
+  }
+]

sonar-server/src/test/java/org/sonar/server/component/ws/ProjectsWsTest.java

@@ -30,30 +30,45 @@ import static org.fest.assertions.Assertions.assertThat;
 
 public class ProjectsWsTest {
 
-  WsTester tester;
+  WebService.Controller controller;
 
   @Before
   public void setUp() throws Exception {
-    tester = new WsTester(new ProjectsWs());
+    WsTester tester = new WsTester(new ProjectsWs());
+    controller = tester.controller("api/projects");
   }
 
   @Test
   public void define_controller() throws Exception {
-    WebService.Controller controller = tester.controller("api/projects");
     assertThat(controller).isNotNull();
     assertThat(controller.description()).isNotEmpty();
-    assertThat(controller.since()).isEqualTo("4.0");
-    assertThat(controller.actions()).hasSize(1);
+    assertThat(controller.since()).isEqualTo("2.10");
+    assertThat(controller.actions()).hasSize(3);
   }
 
   @Test
-  public void define_create_action() throws Exception {
-    WebService.Controller controller = tester.controller("api/projects");
+  public void define_index_action() throws Exception {
+    WebService.Action action = controller.action("index");
+    assertThat(action).isNotNull();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.responseExampleAsString()).isNotEmpty();
+    assertThat(action.params()).hasSize(7);
+  }
 
+  @Test
+  public void define_create_action() throws Exception {
     WebService.Action action = controller.action("create");
     assertThat(action).isNotNull();
     assertThat(action.handler()).isInstanceOf(RailsHandler.class);
     assertThat(action.params()).hasSize(2);
   }
 
+  @Test
+  public void define_destroy_action() throws Exception {
+    WebService.Action action = controller.action("destroy");
+    assertThat(action).isNotNull();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.params()).hasSize(1);
+  }
+
 }