SONAR-5111 Add api/resources WS documentations

3 files changed, 166 insertions, 2 deletions

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