SONAR-5111 Add api/components WS documentations

13 files changed, 195 insertions, 11 deletions

diff --git a/sonar-server/src/main/java/org/sonar/server/component/ws/ComponentsWs.java b/sonar-server/src/main/java/org/sonar/server/component/ws/ComponentsWs.java
new file mode 100644
index 00000000000..e8e03caf642
--- /dev/null
+++ b/sonar-server/src/main/java/org/sonar/server/component/ws/ComponentsWs.java
@@ -0,0 +1,54 @@
+/*
+ * 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.
+ */
+
+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;
+
+public class ComponentsWs implements WebService {
+
+  @Override
+  public void define(Context context) {
+    NewController controller = context.createController("api/components")
+      .setSince("4.2")
+      .setDescription("Components management");
+
+    defineSuggestionsAction(controller);
+
+    controller.done();
+  }
+
+  private void defineSuggestionsAction(NewController controller) {
+    NewAction action = controller.createAction("suggestions")
+      .setDescription("Internal WS for the top-right search engine")
+      .setSince("4.2")
+      .setInternal(true)
+      .setHandler(RailsHandler.INSTANCE)
+      .setResponseExample(Resources.getResource(this.getClass(), "components-example-suggestions.json"));
+
+    action.createParam("s")
+      .setRequired(true)
+      .setDescription("Substring of project key (minimum 2 characters)")
+      .setExampleValue("sonar");
+  }
+
+}
diff --git a/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java b/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
index bc097e24dc0..532fe26033a 100644
--- a/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
+++ b/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
@@ -44,14 +44,14 @@ public class ProjectsWs implements WebService {
       .setDescription("Search for projects")
       .setSince("2.10")
       .setHandler(RailsHandler.INSTANCE)
-      .setResponseExample(Resources.getResource(this.getClass(), "example-index.json"));
+      .setResponseExample(Resources.getResource(this.getClass(), "projects-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")
+      .setDescription("Substring of project name, case insensitive")
       .setExampleValue("Sonar");
 
     action.createParam("desc")
diff --git a/sonar-server/src/main/java/org/sonar/server/measure/ws/ResourcesWs.java b/sonar-server/src/main/java/org/sonar/server/component/ws/ResourcesWs.java
index af40552150d..f402080f550 100644
--- a/sonar-server/src/main/java/org/sonar/server/measure/ws/ResourcesWs.java
+++ b/sonar-server/src/main/java/org/sonar/server/component/ws/ResourcesWs.java
@@ -18,7 +18,7 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
 
-package org.sonar.server.measure.ws;
+package org.sonar.server.component.ws;
 
 import com.google.common.io.Resources;
 import org.sonar.api.server.ws.RailsHandler;
diff --git a/sonar-server/src/main/java/org/sonar/server/platform/ServerComponents.java b/sonar-server/src/main/java/org/sonar/server/platform/ServerComponents.java
index 6d77d56c5e7..3912430445a 100644
--- a/sonar-server/src/main/java/org/sonar/server/platform/ServerComponents.java
+++ b/sonar-server/src/main/java/org/sonar/server/platform/ServerComponents.java
@@ -81,7 +81,9 @@ import org.sonar.server.charts.ChartFactory;
 import org.sonar.server.cluster.LocalNonBlockingWorkQueue;
 import org.sonar.server.component.DefaultComponentFinder;
 import org.sonar.server.component.DefaultRubyComponentService;
+import org.sonar.server.component.ws.ComponentsWs;
 import org.sonar.server.component.ws.ProjectsWs;
+import org.sonar.server.component.ws.ResourcesWs;
 import org.sonar.server.db.EmbeddedDatabaseFactory;
 import org.sonar.server.db.migrations.DatabaseMigrations;
 import org.sonar.server.db.migrations.DatabaseMigrator;
@@ -96,7 +98,6 @@ import org.sonar.server.issue.filter.IssueFilterWriter;
 import org.sonar.server.issue.filter.IssueFilterWs;
 import org.sonar.server.issue.ws.IssueShowAction;
 import org.sonar.server.issue.ws.IssuesWs;
-import org.sonar.server.measure.ws.ResourcesWs;
 import org.sonar.server.measure.ws.TimeMachineWs;
 import org.sonar.server.notifications.NotificationCenter;
 import org.sonar.server.notifications.NotificationService;
@@ -112,8 +113,8 @@ import org.sonar.server.qualitygate.QualityGates;
 import org.sonar.server.qualitygate.RegisterQualityGates;
 import org.sonar.server.qualitygate.ws.*;
 import org.sonar.server.qualityprofile.*;
-import org.sonar.server.qualityprofile.ws.QProfileRestoreDefaultAction;
 import org.sonar.server.qualityprofile.ws.ProfilesWs;
+import org.sonar.server.qualityprofile.ws.QProfileRestoreDefaultAction;
 import org.sonar.server.rule.*;
 import org.sonar.server.rule.ws.*;
 import org.sonar.server.rule2.RuleService;
@@ -378,6 +379,7 @@ class ServerComponents {
     pico.addSingleton(DefaultRubyComponentService.class);
     pico.addSingleton(ComponentDao.class);
     pico.addSingleton(ResourcesWs.class);
+    pico.addSingleton(ComponentsWs.class);
     pico.addSingleton(ProjectsWs.class);
 
     // issues
diff --git a/sonar-server/src/main/java/org/sonar/server/source/ws/ShowAction.java b/sonar-server/src/main/java/org/sonar/server/source/ws/ShowAction.java
index 6545209aa70..d3a3ad31d34 100644
--- a/sonar-server/src/main/java/org/sonar/server/source/ws/ShowAction.java
+++ b/sonar-server/src/main/java/org/sonar/server/source/ws/ShowAction.java
@@ -69,7 +69,8 @@ public class ShowAction implements RequestHandler {
     action
       .createParam("scm")
       .setDescription("Enable loading of SCM information per line")
-      .setBooleanPossibleValues();
+      .setBooleanPossibleValues()
+      .setDefaultValue("false");
 
     action
       .createParam("group_commits")
diff --git a/sonar-server/src/main/resources/org/sonar/server/component/ws/components-example-suggestions.json b/sonar-server/src/main/resources/org/sonar/server/component/ws/components-example-suggestions.json
new file mode 100644
index 00000000000..3640790c0a2
--- /dev/null
+++ b/sonar-server/src/main/resources/org/sonar/server/component/ws/components-example-suggestions.json
@@ -0,0 +1,67 @@
+{
+  "total": 101,
+  "results": [
+    {
+      "q": "TRK",
+      "icon": "/images/q/TRK.png",
+      "name": "Projects",
+      "items": [
+        {
+          "id": 2865,
+          "name": "SonarQube"
+        },
+        {
+          "id": 13265,
+          "name": "SonarQube Java"
+        },
+        {
+          "id": 17226,
+          "name": "SonarQube Runner"
+        },
+        {
+          "id": 12916,
+          "name": "SonarQube C# Plugin"
+        },
+        {
+          "id": 15021,
+          "name": "SonarQube PMD Plugin"
+        },
+        {
+          "id": 5537,
+          "name": "SonarQube Web Plugin"
+        }
+      ]
+    },
+    {
+      "q": "BRC",
+      "icon": "/images/q/BRC.png",
+      "name": "Sub-projects",
+      "items": [
+        {
+          "id": 17221,
+          "name": "SonarQube :: Home"
+        },
+        {
+          "id": 258,
+          "name": "SonarQube :: Core"
+        },
+        {
+          "id": 1624,
+          "name": "SonarQube :: Batch"
+        },
+        {
+          "id": 21,
+          "name": "SonarQube :: Graph"
+        },
+        {
+          "id": 2872,
+          "name": "SonarQube :: Server"
+        },
+        {
+          "id": 2869,
+          "name": "SonarQube :: Markdown"
+        }
+      ]
+    }
+  ]
+}
diff --git a/sonar-server/src/main/resources/org/sonar/server/component/ws/example-index.json b/sonar-server/src/main/resources/org/sonar/server/component/ws/projects-example-index.json
index a5d82ab23c3..a5d82ab23c3 100644
--- a/sonar-server/src/main/resources/org/sonar/server/component/ws/example-index.json
+++ b/sonar-server/src/main/resources/org/sonar/server/component/ws/projects-example-index.json
diff --git a/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-index.json b/sonar-server/src/main/resources/org/sonar/server/component/ws/resources-example-index.json
index 78e28adf94e..78e28adf94e 100644
--- a/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-index.json
+++ b/sonar-server/src/main/resources/org/sonar/server/component/ws/resources-example-index.json
diff --git a/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-search.json b/sonar-server/src/main/resources/org/sonar/server/component/ws/resources-example-search.json
index fc4c74ae1a6..fc4c74ae1a6 100644
--- a/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-search.json
+++ b/sonar-server/src/main/resources/org/sonar/server/component/ws/resources-example-search.json
diff --git a/sonar-server/src/test/java/org/sonar/server/component/ws/ComponentsWsTest.java b/sonar-server/src/test/java/org/sonar/server/component/ws/ComponentsWsTest.java
new file mode 100644
index 00000000000..d7b235704a9
--- /dev/null
+++ b/sonar-server/src/test/java/org/sonar/server/component/ws/ComponentsWsTest.java
@@ -0,0 +1,60 @@
+/*
+ * 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.
+ */
+
+package org.sonar.server.component.ws;
+
+import org.junit.Before;
+import org.junit.Test;
+import org.sonar.api.server.ws.RailsHandler;
+import org.sonar.api.server.ws.WebService;
+import org.sonar.server.ws.WsTester;
+
+import static org.fest.assertions.Assertions.assertThat;
+
+public class ComponentsWsTest {
+
+  WebService.Controller controller;
+
+  @Before
+  public void setUp() throws Exception {
+    WsTester tester = new WsTester(new ComponentsWs());
+    controller = tester.controller("api/components");
+  }
+
+  @Test
+  public void define_controller() throws Exception {
+    assertThat(controller).isNotNull();
+    assertThat(controller.description()).isNotEmpty();
+    assertThat(controller.since()).isEqualTo("4.2");
+    assertThat(controller.actions()).hasSize(1);
+  }
+
+  @Test
+  public void define_suggestions_action() throws Exception {
+    WebService.Action action = controller.action("suggestions");
+    assertThat(action).isNotNull();
+    assertThat(action.isInternal()).isTrue();
+    assertThat(action.isPost()).isFalse();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.responseExampleAsString()).isNotEmpty();
+    assertThat(action.params()).hasSize(1);
+  }
+
+}
diff --git a/sonar-server/src/test/java/org/sonar/server/measure/ws/ResourcesWsTest.java b/sonar-server/src/test/java/org/sonar/server/component/ws/ResourcesWsTest.java
index 6dab985c81c..8609d26d1d5 100644
--- a/sonar-server/src/test/java/org/sonar/server/measure/ws/ResourcesWsTest.java
+++ b/sonar-server/src/test/java/org/sonar/server/component/ws/ResourcesWsTest.java
@@ -18,7 +18,7 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
 
-package org.sonar.server.measure.ws;
+package org.sonar.server.component.ws;
 
 import org.junit.Before;
 import org.junit.Test;
diff --git a/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list.json b/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list.json
index 2d522866dd0..ce70fc276c6 100644
--- a/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list.json
+++ b/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list.json
@@ -48,10 +48,10 @@
         "params": [
           {
             "key": "include_internals",
-            "description": "Include web services that are implemented for internal use only. Their forward-compatibility is not assured.",
+            "description": "Include web services that are implemented for internal use only. Their forward-compatibility is not assured",
             "required": false,
             "defaultValue": "false",
-            "possibleValues": ["false", "true"]
+            "possibleValues": ["true", "false"]
           }
         ]
       },
diff --git a/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list_including_internals.json b/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list_including_internals.json
index 15c3bd6a7a0..82631afb3b4 100644
--- a/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list_including_internals.json
+++ b/sonar-server/src/test/resources/org/sonar/server/ws/ListingWsTest/list_including_internals.json
@@ -55,10 +55,10 @@
         "params": [
           {
             "key": "include_internals",
-            "description": "Include web services that are implemented for internal use only. Their forward-compatibility is not assured.",
+            "description": "Include web services that are implemented for internal use only. Their forward-compatibility is not assured",
             "required": false,
             "defaultValue": "false",
-            "possibleValues": ["false", "true"]
+            "possibleValues": ["true", "false"]
           }
         ]
       },