SONAR-5111 Add api/resources WS documentations

9 files changed, 295 insertions, 4 deletions

diff --git a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
index c84994096f8..7f6e012ec3f 100644
--- a/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
+++ b/sonar-plugin-api/src/main/java/org/sonar/api/server/ws/WebService.java
@@ -159,7 +159,7 @@ public interface WebService extends ServerExtension {
     }
 
     /**
-     * Optional plain-text description
+     * Optional description (accept HTML)
      */
     public NewController setDescription(@Nullable String s) {
       this.description = s;
diff --git a/sonar-server/src/main/java/org/sonar/server/measure/ws/ResourcesWs.java b/sonar-server/src/main/java/org/sonar/server/measure/ws/ResourcesWs.java
new file mode 100644
index 00000000000..13220ced3dd
--- /dev/null
+++ b/sonar-server/src/main/java/org/sonar/server/measure/ws/ResourcesWs.java
@@ -0,0 +1,160 @@
+/*
+ * 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.measure.ws;
+
+import com.google.common.io.Resources;
+import org.sonar.api.server.ws.RailsHandler;
+import org.sonar.api.server.ws.WebService;
+
+public class ResourcesWs implements WebService {
+
+  @Override
+  public void define(Context context) {
+    NewController controller = context.createController("api/resources")
+      .setSince("2.10");
+
+    defineSystemAction(controller);
+    defineSearchAction(controller);
+
+    controller.done();
+  }
+
+  private void defineSystemAction(NewController controller) {
+    NewAction action = controller.createAction("index")
+      .setDescription("Get a list of components. Requires Browse permission on resource")
+      .setSince("2.10")
+      .setHandler(RailsHandler.INSTANCE)
+      .setResponseExample(Resources.getResource(this.getClass(), "resources-example-index.json"));
+
+    action.createParam("resource")
+      .setDescription("id or key of the resource")
+      .setExampleValue("org.codehaus.sonar:sonar");
+
+    action.createParam("metrics")
+      .setDescription("Comma-separated list of <a href=\"http://docs.codehaus.org/display/SONAR/Metric+definitions\">metric keys/ids</a>. " +
+        "Load measures on selected metrics. If only one metric is set, then measures are ordered by value.")
+      .setExampleValue("lines,blocker_violations");
+
+    action.createParam("depth")
+      .setDescription("Used only when resource is set.<br/>" +
+        "<ul>" +
+        "<li>0: only selected resource</li>" +
+        "<li>-1: all children, including selected resource</li>" +
+        "<li>>0: depth toward the selected resource</li>" +
+        "</ul>")
+      .setDefaultValue("0")
+      .setExampleValue("-1");
+
+    action.createParam("scopes")
+      .setDescription("Comma-separated list of scopes:<br/>" +
+        "<ul>" +
+        "<li>PRJ: project/module</li>" +
+        "<li>DIR: directory (like Java package)</li>" +
+        "<li>FIL: file</li>" +
+        "</ul>")
+      .setExampleValue("PRJ,DIR");
+
+    action.createParam("qualifiers")
+      .setDescription("Comma-separated list of qualifiers:<br/>" +
+        "<ul>" +
+        "<li>VW: view</li>" +
+        "<li>SVW: sub-view</li>" +
+        "<li>TRK: project</li>" +
+        "<li>BRC: module</li>" +
+        "<li>UTS: unit test</li>" +
+        "<li>DIR: directory</li>" +
+        "<li>FIL: file</li>" +
+        "<li>DEV: developer</li>" +
+        "</ul>")
+      .setExampleValue("TRK,BRC");
+
+    action.createParam("verbose")
+      .setDescription("Add some data to response")
+      .setDefaultValue("false")
+      .setPossibleValues("true", "false")
+      .setExampleValue("true");
+
+    action.createParam("limit")
+      .setDescription("Limit the number of results. Only used if one metric, and only one, is set")
+      .setExampleValue("10");
+
+    action.createParam("includetrends")
+      .setDescription("Include trends and period variations in response: add <trend> (1 if better, else worse), <var> (1 if measure value increases) " +
+        "and nodes <p*> for period variations")
+      .setDefaultValue("false")
+      .setPossibleValues("true", "false")
+      .setExampleValue("true");
+
+    action.createParam("includealerts")
+      .setDescription("Include alerts data: add nodes <alert> (ERROR, WARN, OK) and <alert_text>")
+      .setDefaultValue("false")
+      .setPossibleValues("true", "false")
+      .setExampleValue("true");
+
+    action.createParam("rules")
+      .setDescription("Filter on rules: setting it to true will return rules id and rule name for measure having such info " +
+        "(such as 'blocker_violations', 'critical_violations', ..., 'new_blocker_violations', ...). Possible values: true | false | list of rule ids")
+      .setDefaultValue("false")
+      .setExampleValue("true");
+  }
+
+  private void defineSearchAction(NewController controller) {
+    NewAction action = controller.createAction("search")
+      .setDescription("Search for components")
+      .setSince("3.3")
+      .setInternal(true)
+      .setHandler(RailsHandler.INSTANCE)
+      .setResponseExample(Resources.getResource(this.getClass(), "resources-example-search.json"));
+
+    action.createParam("s")
+      .setDescription("To filter on resources containing a specified text in their key")
+      .setExampleValue("sonar");
+
+    action.createParam("display_key")
+      .setDescription("Return the resource key instead of the resource id")
+      .setDefaultValue("false")
+      .setPossibleValues("true", "false")
+      .setExampleValue("true");
+
+    action.createParam("q")
+      .setDescription("Comma-separated list of qualifiers")
+      .setExampleValue("TRK,BRC");
+
+    action.createParam("qp")
+      .setDescription("Resource Property")
+      .setExampleValue("supportsMeasureFilters");
+
+    action.createParam("f")
+      .setDescription("If 's2', then it will return a select2 compatible format")
+      .setExampleValue("s2");
+
+    action.createParam("p")
+      .setDescription("Page index")
+      .setDefaultValue("1")
+      .setExampleValue("2");
+
+    action.createParam("ps")
+      .setDescription("Page size")
+      .setDefaultValue("10")
+      .setExampleValue("15");
+  }
+
+}
diff --git a/sonar-server/src/main/java/org/sonar/server/measure/ws/TimeMachineWs.java b/sonar-server/src/main/java/org/sonar/server/measure/ws/TimeMachineWs.java
index 64de3f505b5..990ac5b7f2e 100644
--- a/sonar-server/src/main/java/org/sonar/server/measure/ws/TimeMachineWs.java
+++ b/sonar-server/src/main/java/org/sonar/server/measure/ws/TimeMachineWs.java
@@ -41,7 +41,7 @@ public class TimeMachineWs implements WebService {
       .setDescription("Get a list of past measures. Requires Browse permission on project")
       .setSince("2.10")
       .setHandler(RailsHandler.INSTANCE)
-      .setResponseExample(Resources.getResource(this.getClass(), "example-index.json"));
+      .setResponseExample(Resources.getResource(this.getClass(), "timemachine-example-index.json"));
 
     action.createParam("resource")
       .setDescription("id or key of the resource (ie: component)")
@@ -49,7 +49,7 @@ public class TimeMachineWs implements WebService {
       .setExampleValue("org.codehaus.sonar:sonar");
 
     action.createParam("metrics")
-      .setDescription("Comma-separated list of metric keys/ids")
+      .setDescription("Comma-separated list of <a href=\"http://docs.codehaus.org/display/SONAR/Metric+definitions\">metric keys/ids</a>")
       .setRequired(true)
       .setExampleValue("coverage,violations_density");
 
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 ad76a583286..614013342a3 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
@@ -96,6 +96,8 @@ 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;
 import org.sonar.server.permission.InternalPermissionService;
@@ -317,6 +319,7 @@ class ServerComponents {
     pico.addSingleton(MeasureFilterEngine.class);
     pico.addSingleton(DefaultMetricFinder.class);
     pico.addSingleton(ServerLifecycleNotifier.class);
+    pico.addSingleton(TimeMachineWs.class);
 
     // quality gates
     pico.addSingleton(QualityGateDao.class);
@@ -370,6 +373,7 @@ class ServerComponents {
     pico.addSingleton(DefaultComponentFinder.class);
     pico.addSingleton(DefaultRubyComponentService.class);
     pico.addSingleton(ComponentDao.class);
+    pico.addSingleton(ResourcesWs.class);
     pico.addSingleton(ProjectsWs.class);
 
     // issues
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/measure/ws/resources-example-index.json
new file mode 100644
index 00000000000..78e28adf94e
--- /dev/null
+++ b/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-index.json
@@ -0,0 +1,35 @@
+[
+  {
+    "id": 2865,
+    "key": "org.codehaus.sonar:sonar",
+    "name": "Sonar",
+    "scope": "PRJ",
+    "qualifier": "TRK",
+    "date": "2012-08-10T04:03:51+0200",
+    "creationDate": "2012-08-10T04:03:51+0200",
+    "lname": "Sonar",
+    "lang": "java",
+    "version": "3.3-SNAPSHOT",
+    "description": "Open source platform for continuous inspection of code quality",
+
+    "p1": "previous_analysis",
+    "p1p": "2012-08-09",
+    "p1d": "2012-08-09T04:04:01+0200",
+    "p2": "days",
+    "p2p": "7",
+    "p2d": "2012-08-03T04:03:51+0200",
+    "msr": [
+      {
+        "key": "coverage",
+        "val": 70.3,
+        "frmt_val": "70.3%",
+        "alert": null,
+        "alert_text": null,
+        "trend": 0,
+        "var": 0,
+        "var1": 0.0,
+        "var2": 0.0
+      }
+    ]
+  }
+]
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/measure/ws/resources-example-search.json
new file mode 100644
index 00000000000..fc4c74ae1a6
--- /dev/null
+++ b/sonar-server/src/main/resources/org/sonar/server/measure/ws/resources-example-search.json
@@ -0,0 +1,25 @@
+{
+  "total": 405,
+  "page": 1,
+  "page_size": 10,
+  "data": [
+    {
+      "id": 21434,
+      "key": "org.codehaus.mojo:sonar-maven-plugin:src/main/java/org/codehaus/mojo/sonar/SonarMojo.java",
+      "nm": "src/main/java/org/codehaus/mojo/sonar/SonarMojo.java",
+      "q": "FIL"
+    },
+    {
+      "id": 4138,
+      "key": "org.codehaus.sonar:sonar-ws-client:src/main/java/org/sonar/wsclient/Sonar.java",
+      "nm": "src/main/java/org/sonar/wsclient/Sonar.java",
+      "q": "FIL"
+    },
+    {
+      "id": 3868,
+      "key": "org.codehaus.sonar:sonar-server:src/main/java/org/sonar/server/platform/SonarHome.java",
+      "nm": "src/main/java/org/sonar/server/platform/SonarHome.java",
+      "q": "FIL"
+    }
+  ]
+}
diff --git a/sonar-server/src/main/resources/org/sonar/server/measure/ws/example-index.json b/sonar-server/src/main/resources/org/sonar/server/measure/ws/timemachine-example-index.json
index 0fb7a624359..0fb7a624359 100644
--- a/sonar-server/src/main/resources/org/sonar/server/measure/ws/example-index.json
+++ b/sonar-server/src/main/resources/org/sonar/server/measure/ws/timemachine-example-index.json
diff --git a/sonar-server/src/test/java/org/sonar/server/measure/ws/ResourcesWsTest.java b/sonar-server/src/test/java/org/sonar/server/measure/ws/ResourcesWsTest.java
new file mode 100644
index 00000000000..6dab985c81c
--- /dev/null
+++ b/sonar-server/src/test/java/org/sonar/server/measure/ws/ResourcesWsTest.java
@@ -0,0 +1,68 @@
+/*
+ * 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.measure.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 ResourcesWsTest {
+
+  WebService.Controller controller;
+
+  @Before
+  public void setUp() throws Exception {
+    WsTester tester = new WsTester(new ResourcesWs());
+    controller = tester.controller("api/resources");
+  }
+
+  @Test
+  public void define_controller() throws Exception {
+    assertThat(controller).isNotNull();
+    assertThat(controller.since()).isEqualTo("2.10");
+    assertThat(controller.description()).isNull();
+    assertThat(controller.actions()).hasSize(2);
+  }
+
+  @Test
+  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(10);
+  }
+
+  @Test
+  public void define_search_action() throws Exception {
+    WebService.Action action = controller.action("search");
+    assertThat(action).isNotNull();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.isInternal()).isTrue();
+    assertThat(action.responseExampleAsString()).isNotEmpty();
+    assertThat(action.params()).hasSize(7);
+  }
+
+}
diff --git a/sonar-server/src/test/java/org/sonar/server/measure/ws/TimeMachineWsTest.java b/sonar-server/src/test/java/org/sonar/server/measure/ws/TimeMachineWsTest.java
index f79b9ba091a..74766ad2a2c 100644
--- a/sonar-server/src/test/java/org/sonar/server/measure/ws/TimeMachineWsTest.java
+++ b/sonar-server/src/test/java/org/sonar/server/measure/ws/TimeMachineWsTest.java
@@ -30,7 +30,6 @@ import static org.fest.assertions.Assertions.assertThat;
 
 public class TimeMachineWsTest {
 
-
   WebService.Controller controller;
 
   @Before