SONAR-9826 Document date format required in the Web API

8 files changed, 45 insertions, 30 deletions

diff --git a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/ComponentTagsAction.java b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/ComponentTagsAction.java
index 45f0347a9ae..a28c041a372 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/ComponentTagsAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/ComponentTagsAction.java
@@ -58,13 +58,17 @@ public class ComponentTagsAction implements IssuesWsAction {
       .setInternal(true)
       .setDescription("List tags for the issues under a given component (including issues on the descendants of the component)")
       .setResponseExample(Resources.getResource(getClass(), "component-tags-example.json"));
+
     action.createParam(PARAM_COMPONENT_UUID)
       .setDescription("A component UUID")
       .setRequired(true)
       .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92");
+
     action.createParam(PARAM_CREATED_AFTER)
-      .setDescription("To retrieve tags on issues created after the given date (inclusive). Format: date or datetime ISO formats")
-      .setExampleValue("2013-05-01 (or 2013-05-01T13:00:00+0100)");
+      .setDescription("To retrieve tags on issues created after the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided.")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
+
     action.createParam(PAGE_SIZE)
       .setDescription("The maximum size of the list to return")
       .setExampleValue("25")
diff --git a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
index e9fac5edb66..f4883716271 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/issue/ws/SearchAction.java
@@ -205,14 +205,17 @@ public class SearchAction implements IssuesWsAction {
       .setDescription("Comma-separated list of languages. Available since 4.4")
       .setExampleValue("java,js");
     action.createParam(PARAM_CREATED_AT)
-      .setDescription("To retrieve issues created in a specific analysis, identified by an ISO-formatted datetime stamp.")
-      .setExampleValue("2013-05-01T13:00:00+0100");
+      .setDescription("Datetime to retrieve issues created during a specific analysis")
+      .setExampleValue("2017-10-19T13:00:00+0200");
     action.createParam(PARAM_CREATED_AFTER)
-      .setDescription("To retrieve issues created after the given date (inclusive). Format: date or datetime ISO formats. If this parameter is set, createdSince must not be set")
-      .setExampleValue("2013-05-01 (or 2013-05-01T13:00:00+0100)");
+      .setDescription("To retrieve issues created after the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided. <br>" +
+        "If this parameter is set, createdSince must not be set")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
     action.createParam(PARAM_CREATED_BEFORE)
-      .setDescription("To retrieve issues created before the given date (exclusive). Format: date or datetime ISO formats")
-      .setExampleValue("2013-05-01 (or 2013-05-01T13:00:00+0100)");
+      .setDescription("To retrieve issues created before the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided.")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
     action.createParam(PARAM_CREATED_IN_LAST)
       .setDescription("To retrieve issues created during a time span before the current time (exclusive). " +
         "Accepted units are 'y' for year, 'm' for month, 'w' for week and 'd' for day. " +
@@ -439,7 +442,7 @@ public class SearchAction implements IssuesWsAction {
     }
   }
 
-  private void collectFacets(SearchResponseLoader.Collector collector, Facets facets) {
+  private static void collectFacets(SearchResponseLoader.Collector collector, Facets facets) {
     Set<String> facetRules = facets.getBucketKeys(PARAM_RULES);
     if (facetRules != null) {
       collector.addAll(SearchAdditionalField.RULES, Collections2.transform(facetRules, RuleKey::parse));
@@ -451,7 +454,7 @@ public class SearchAction implements IssuesWsAction {
     collector.addAll(SearchAdditionalField.USERS, facets.getBucketKeys(PARAM_ASSIGNEES));
   }
 
-  private void collectRequestParams(SearchResponseLoader.Collector collector, SearchWsRequest request) {
+  private static void collectRequestParams(SearchResponseLoader.Collector collector, SearchWsRequest request) {
     collector.addProjectUuids(request.getProjectUuids());
     collector.addComponentUuids(request.getFileUuids());
     collector.addComponentUuids(request.getModuleUuids());
diff --git a/server/sonar-server/src/main/java/org/sonar/server/measure/ws/SearchHistoryAction.java b/server/sonar-server/src/main/java/org/sonar/server/measure/ws/SearchHistoryAction.java
index 47f9b31938e..d9adb3dbd0f 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/measure/ws/SearchHistoryAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/measure/ws/SearchHistoryAction.java
@@ -114,12 +114,14 @@ public class SearchHistoryAction implements MeasuresWsAction {
       .setExampleValue("ncloc,coverage,new_violations");
 
     action.createParam(PARAM_FROM)
-      .setDescription("Filter measures created after the given date (inclusive). Format: date or datetime ISO formats")
-      .setExampleValue("2013-05-01T13:00:00+0100");
+      .setDescription("Filter measures created after the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
 
     action.createParam(PARAM_TO)
-      .setDescription("Filter measures created before the given date (inclusive). Format: date or datetime ISO formats")
-      .setExampleValue("2013-05-01");
+      .setDescription("Filter measures created before the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
 
     action.addPagingParams(DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
   }
diff --git a/server/sonar-server/src/main/java/org/sonar/server/permission/ws/template/BulkApplyTemplateAction.java b/server/sonar-server/src/main/java/org/sonar/server/permission/ws/template/BulkApplyTemplateAction.java
index f3e75e9ae84..b5cdd5f896e 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/permission/ws/template/BulkApplyTemplateAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/permission/ws/template/BulkApplyTemplateAction.java
@@ -119,8 +119,10 @@ public class BulkApplyTemplateAction implements PermissionsWsAction {
 
     action.createParam(PARAM_ANALYZED_BEFORE)
       .setDescription("Filter the projects for which last analysis is older than the given date (exclusive).<br> " +
-        "Format: date or datetime ISO formats.")
-      .setSince("6.6");
+        "Either a date (server timezone) or datetime can be provided.")
+      .setSince("6.6")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200")
+    ;
 
     action.createParam(PARAM_ON_PROVISIONED_ONLY)
       .setDescription("Filter the projects that are provisioned")
diff --git a/server/sonar-server/src/main/java/org/sonar/server/project/ws/BulkDeleteAction.java b/server/sonar-server/src/main/java/org/sonar/server/project/ws/BulkDeleteAction.java
index 1b756893732..ec129767b14 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/project/ws/BulkDeleteAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/project/ws/BulkDeleteAction.java
@@ -114,8 +114,9 @@ public class BulkDeleteAction implements ProjectsWsAction {
 
     action.createParam(PARAM_ANALYZED_BEFORE)
       .setDescription("Filter the projects for which last analysis is older than the given date (exclusive).<br> " +
-        "Format: date or datetime ISO formats.")
-      .setSince("6.6");
+        "Either a date (server timezone) or datetime can be provided.")
+      .setSince("6.6")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
 
     action.createParam(PARAM_ON_PROVISIONED_ONLY)
       .setDescription("Filter the projects that are provisioned")
diff --git a/server/sonar-server/src/main/java/org/sonar/server/project/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/project/ws/SearchAction.java
index 1be8cde92c1..03a235e2c61 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/project/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/project/ws/SearchAction.java
@@ -116,8 +116,9 @@ public class SearchAction implements ProjectsWsAction {
 
     action.createParam(PARAM_ANALYZED_BEFORE)
       .setDescription("Filter the projects for which last analysis is older than the given date (exclusive).<br> " +
-        "Format: date or datetime ISO formats.")
-      .setSince("6.6");
+        "Either a date (server timezone) or datetime can be provided.")
+      .setSince("6.6")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
 
     action.createParam(PARAM_ON_PROVISIONED_ONLY)
       .setDescription("Filter the projects that are provisioned")
diff --git a/server/sonar-server/src/main/java/org/sonar/server/projectanalysis/ws/SearchAction.java b/server/sonar-server/src/main/java/org/sonar/server/projectanalysis/ws/SearchAction.java
index 455441d3a12..8729785236d 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/projectanalysis/ws/SearchAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/projectanalysis/ws/SearchAction.java
@@ -100,13 +100,15 @@ public class SearchAction implements ProjectAnalysesWsAction {
       .setExampleValue(OTHER.name());
 
     action.createParam(PARAM_FROM)
-      .setDescription("Filter analyses created after the given date (inclusive). Format: date or datetime ISO formats")
+      .setDescription("Filter analyses created after the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided")
       .setExampleValue("2013-05-01")
       .setSince("6.5");
 
     action.createParam(PARAM_TO)
-      .setDescription("Filter analyses created before the given date (inclusive). Format: date or datetime ISO formats")
-      .setExampleValue("2013-05-01T13:00:00+0100")
+      .setDescription("Filter analyses created before the given date (inclusive). <br>" +
+        "Either a date (server timezone) or datetime can be provided")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200")
       .setSince("6.5");
 
   }
diff --git a/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java b/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
index 86a12266131..5a7073c20d7 100644
--- a/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
+++ b/server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/ChangelogAction.java
@@ -81,12 +81,14 @@ public class ChangelogAction implements QProfileWsAction {
     wsAction.addPagingParams(50, MAX_LIMIT);
 
     wsAction.createParam(PARAM_SINCE)
-      .setDescription("Start date for the changelog.")
-      .setExampleValue("2011-04-25T01:15:42+0100");
+      .setDescription("Start date for the changelog. <br>" +
+        "Either a date (server timezone) or datetime can be provided.")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
 
     wsAction.createParam(PARAM_TO)
-      .setDescription("End date for the changelog.")
-      .setExampleValue("2013-07-25T07:35:42+0200");
+      .setDescription("End date for the changelog. <br>" +
+        "Either a date (server timezone) or datetime can be provided.")
+      .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200");
   }
 
   @Override
@@ -145,7 +147,6 @@ public class ChangelogAction implements QProfileWsAction {
     json.endObject();
   }
 
-
   /**
    * @return non-null list of changes, by descending order of date
    */
@@ -177,7 +178,6 @@ public class ChangelogAction implements QProfileWsAction {
     });
   }
 
-
   static class Change {
     private String key;
     private String type;
@@ -195,7 +195,7 @@ public class ChangelogAction implements QProfileWsAction {
 
     @VisibleForTesting
     Change(String key, String type, long at, @Nullable String severity, @Nullable String userLogin,
-           @Nullable String userName, @Nullable String inheritance, @Nullable RuleKey ruleKey, @Nullable String ruleName) {
+      @Nullable String userName, @Nullable String inheritance, @Nullable RuleKey ruleKey, @Nullable String ruleName) {
       this.key = key;
       this.type = type;
       this.at = at;