PLUGINAPI-94 added enum to define response type for the endpoints

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 10.8
 
+* Fixed an issue where WebService which was not meant to return any response still showed the warning in the logs when response example was not set.
+* Introduced 'org.sonar.api.server.ws.WebService.NewAction.setContentType' for optionally setting a response type of Action.
 * Replace internal library `commons-lang:commons-lang` by `org.apache.commons:commons-lang3`.
 * Do not throw an exception when a rule parameter is not known in `org.sonar.api.batch.rule.Checks`
 

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

@@ -65,4 +65,13 @@ interface Stream {
 
   Stream stream();
 
+  /**
+   * The list of content types doesn't necessarily need to correspond to the ones defined in RFC2046.
+   */
+  enum ContentType {
+    NO_CONTENT,
+    BINARY,
+    TEXT
+  }
+
 }

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

@@ -243,6 +243,7 @@ public boolean isInternal() {
   class NewAction {
     private final String key;
     private static final String PAGE_PARAM_DESCRIPTION = "1-based page number";
+    private Enum<Response.ContentType> contentType;
     private String deprecatedKey;
     private String description;
     private String since;
@@ -312,6 +313,15 @@ public NewAction setHandler(RequestHandler h) {
       return this;
     }
 
+    /**
+     * Sets content type of the response. This is optional to do.
+     * @since 10.8
+     */
+    public NewAction setContentType(Enum<Response.ContentType> contentType) {
+      this.contentType = contentType;
+      return this;
+    }
+
     /**
      * Link to the document containing an example of response. Content must be UTF-8 encoded.
      * <br>
@@ -503,6 +513,7 @@ class Action {
     private final Map<String, Param> params;
     private final URL responseExample;
     private final List<Change> changelog;
+    private final Enum<Response.ContentType> contentType;
 
     private Action(Controller controller, NewAction newAction) {
       this.key = newAction.key;
@@ -516,11 +527,12 @@ private Action(Controller controller, NewAction newAction) {
       this.responseExample = newAction.responseExample;
       this.handler = newAction.handler;
       this.changelog = newAction.changelog;
+      this.contentType = newAction.contentType;
 
       checkState(this.handler != null, "RequestHandler is not set on action %s", path);
       logWarningIf(this.description == null || this.description.isEmpty(), "Description is not set on action " + path);
       logWarningIf(this.since == null || this.since.isEmpty(), "Since is not set on action " + path);
-      logWarningIf(!this.post && this.responseExample == null, "The response example is not set on action " + path);
+      logWarningIf(this.responseExample == null && isResponseExampleNeeded(), "The response example is not set on action " + path);
 
       Map<String, Param> paramsBuilder = new HashMap<>();
       for (NewParam newParam : newAction.newParams.values()) {
@@ -529,6 +541,10 @@ private Action(Controller controller, NewAction newAction) {
       this.params = Collections.unmodifiableMap(paramsBuilder);
     }
 
+    private boolean isResponseExampleNeeded() {
+      return !(this.post || this.contentType == Response.ContentType.BINARY || this.contentType == Response.ContentType.NO_CONTENT);
+    }
+
     private static void logWarningIf(boolean condition, String message) {
       if (condition) {
         LOGGER.warn(message);

plugin-api/src/test/java/org/sonar/api/server/ws/WebServiceTest.java

@@ -26,6 +26,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.junit.Rule;
 import org.junit.Test;
+import org.slf4j.event.Level;
 import org.sonar.api.rule.RuleStatus;
 import org.sonar.api.server.ws.WebService.NewAction;
 import org.sonar.api.server.ws.WebService.NewController;
@@ -111,6 +112,21 @@ public void add_changelog_if_called_twice() {
         tuple("2.0", "change2"));
   }
 
+  @Test
+  public void dont_display_warning_if_response_example_is_not_set_on_no_content_endpoint() {
+    WebService webService = ctx -> {
+      NewController newController = ctx.createController("api/custom_action");
+      newDefaultAction(newController, "list")
+        .setResponseExample(null)
+        .setContentType(Response.ContentType.NO_CONTENT);
+      newController.done();
+    };
+
+    webService.define(context);
+
+    assertThat(logTester.getLogs(Level.WARN)).isEmpty();
+  }
+
   @Test
   public void fail_if_duplicated_ws_keys() {
     MetricWs metricWs = new MetricWs();