SONAR-13850: Add missing response examples to WEB API endpoints.

Add response example for 'security_reports/show' endpoint
Add response example for 'project_dump/status' endpoint
Add response example for 'alm_integrations/search_azure_repos' endpoint
Add response example for 'alm_integrations/search_bitbucketserver_repos' endpoint
Add response example for 'alm_integrations/list_azure_projects' endpoint
Add response example for 'alm_integrations/search_bitbucketcloud_repos' endpoint
Add response example for 'alm_integrations/list_bitbucketserver_projects endpoint'

18 files changed, 130 insertions, 2 deletions

diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsAction.java
index dc0a287e492..f585f1c8bdb 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsAction.java
@@ -65,6 +65,7 @@ public class ListAzureProjectsAction implements AlmIntegrationsWsAction {
         "Requires the 'Create Projects' permission")
       .setPost(false)
       .setSince("8.6")
+      .setResponseExample(getClass().getResource("example-list_azure_projects.json"))
       .setHandler(this);
 
     action.createParam(PARAM_ALM_SETTING)
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposAction.java
index c944723ef50..389bfb630c1 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposAction.java
@@ -84,6 +84,7 @@ public class SearchAzureReposAction implements AlmIntegrationsWsAction {
         "Requires the 'Create Projects' permission")
       .setPost(false)
       .setSince("8.6")
+      .setResponseExample(getClass().getResource("example-search_azure_repos.json"))
       .setHandler(this);
 
     action.createParam(PARAM_ALM_SETTING)
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposAction.java
index c0962fd2d83..190bd9f255d 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposAction.java
@@ -79,6 +79,7 @@ public class SearchBitbucketCloudReposAction implements AlmIntegrationsWsAction
         "Requires the 'Create Projects' permission")
       .setPost(false)
       .setSince("9.0")
+      .setResponseExample(getClass().getResource("example-search_bitbucketcloud_repos.json"))
       .setHandler(this);
 
     action.createParam(PARAM_ALM_SETTING)
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsAction.java
index f16e9da9e4a..adcd5339fb6 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsAction.java
@@ -63,6 +63,7 @@ public class ListBitbucketServerProjectsAction implements AlmIntegrationsWsActio
         "Requires the 'Create Projects' permission")
       .setPost(false)
       .setSince("8.2")
+      .setResponseExample(getClass().getResource("example-list_bitbucketserver_projects.json"))
       .setHandler(this);
 
     action.createParam(PARAM_ALM_SETTING)
diff --git a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposAction.java b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposAction.java
index 0bfd91e2f09..fd610071cec 100644
--- a/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposAction.java
+++ b/server/sonar-webserver-webapi/src/main/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposAction.java
@@ -81,6 +81,7 @@ public class SearchBitbucketServerReposAction implements AlmIntegrationsWsAction
         "Requires the 'Create Projects' permission")
       .setPost(false)
       .setSince("8.2")
+      .setResponseExample(getClass().getResource("example-search_bitbucketserver_repos.json"))
       .setHandler(this);
 
     action.createParam(PARAM_ALM_SETTING)
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-list_azure_projects.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-list_azure_projects.json
new file mode 100644
index 00000000000..99e646e5a77
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-list_azure_projects.json
@@ -0,0 +1,12 @@
+{
+  "projects": [
+    {
+      "name": "project1",
+      "description": "description1"
+    },
+    {
+      "name": "project2",
+      "description": "description2"
+    }
+  ]
+}
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-search_azure_repos.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-search_azure_repos.json
new file mode 100644
index 00000000000..dea6d3be4f7
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/azure/example-search_azure_repos.json
@@ -0,0 +1,12 @@
+{
+  "repositories": [
+    {
+      "name": "repoName1",
+      "projectName": "project1"
+    },
+    {
+      "name": "repoName2",
+      "projectName": "project2"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketcloud/example-search_bitbucketcloud_repos.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketcloud/example-search_bitbucketcloud_repos.json
new file mode 100644
index 00000000000..a643d23ac18
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketcloud/example-search_bitbucketcloud_repos.json
@@ -0,0 +1,24 @@
+{
+  "paging": {
+    "pageIndex": 1,
+    "pageSize": 100
+  },
+  "isLastPage": false,
+  "repositories": [
+    {
+      "slug": "repo-slug-1",
+      "uuid": "REPO-UUID-ONE",
+      "name": "repoName1",
+      "projectKey": "projectKey1",
+      "workspace": "60Mna3eiSKjB2JqXucUVXoQMQbl2q0mTxJ2fyR0xfRuAcibVepy7yEfptuuFM3kd3f9v7eKtoT3JPd01"
+    },
+    {
+      "slug": "repo-slug-2",
+      "uuid": "REPO-UUID-TWO",
+      "name": "repoName2",
+      "sqProjectKey": "KEY_01814E2745E7D394BD",
+      "projectKey": "projectKey2",
+      "workspace": "60Mna3eiSKjB2JqXucUVXoQMQbl2q0mTxJ2fyR0xfRuAcibVepy7yEfptuuFM3kd3f9v7eKtoT3JPd01"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-list_bitbucketserver_projects.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-list_bitbucketserver_projects.json
new file mode 100644
index 00000000000..52d4ba77255
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-list_bitbucketserver_projects.json
@@ -0,0 +1,12 @@
+{
+  "projects": [
+    {
+      "key": "key",
+      "name": "name"
+    },
+    {
+      "key": "key2",
+      "name": "name2"
+    }
+  ]
+}
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-search_bitbucketserver_repos.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-search_bitbucketserver_repos.json
new file mode 100644
index 00000000000..57feeed46be
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/almintegration/ws/bitbucketserver/example-search_bitbucketserver_repos.json
@@ -0,0 +1,20 @@
+{
+  "isLastPage": false,
+  "repositories": [
+    {
+      "slug": "repo-slug-1",
+      "uuid": "REPO-UUID-ONE",
+      "name": "repoName1",
+      "projectKey": "projectKey1",
+      "workspace": "60Mna3eiSKjB2JqXucUVXoQMQbl2q0mTxJ2fyR0xfRuAcibVepy7yEfptuuFM3kd3f9v7eKtoT3JPd01"
+    },
+    {
+      "slug": "repo-slug-2",
+      "uuid": "REPO-UUID-TWO",
+      "name": "repoName2",
+      "sqProjectKey": "KEY_01814E2745E7D394BD",
+      "projectKey": "projectKey2",
+      "workspace": "60Mna3eiSKjB2JqXucUVXoQMQbl2q0mTxJ2fyR0xfRuAcibVepy7yEfptuuFM3kd3f9v7eKtoT3JPd01"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/projectdump/ws/example-status.json b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/projectdump/ws/example-status.json
new file mode 100644
index 00000000000..6f116fd36d2
--- /dev/null
+++ b/server/sonar-webserver-webapi/src/main/resources/org/sonar/server/projectdump/ws/example-status.json
@@ -0,0 +1,6 @@
+{
+  "canBeExported": true,
+  "canBeImported": false,
+  "exportedDump": "/data/governance/export/my_project.zip",
+  "dumpToImport": "/data/governance/import/my_project.zip"
+}
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsActionTest.java
index c9d2a57fbfa..6da70e29888 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/ListAzureProjectsActionTest.java
@@ -159,6 +159,7 @@ public class ListAzureProjectsActionTest {
 
     assertThat(def.since()).isEqualTo("8.6");
     assertThat(def.isPost()).isFalse();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
     assertThat(def.params())
       .extracting(WebService.Param::key, WebService.Param::isRequired)
       .containsExactlyInAnyOrder(tuple("almSetting", true));
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposActionTest.java
index ed5f0d84f55..7385919dfaa 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/azure/SearchAzureReposActionTest.java
@@ -77,6 +77,7 @@ public class SearchAzureReposActionTest {
 
     assertThat(def.since()).isEqualTo("8.6");
     assertThat(def.isPost()).isFalse();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
     assertThat(def.params())
       .extracting(WebService.Param::key, WebService.Param::isRequired)
       .containsExactlyInAnyOrder(
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposActionTest.java
index 24ee3f1f116..40063d4020d 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketcloud/SearchBitbucketCloudReposActionTest.java
@@ -184,6 +184,7 @@ public class SearchBitbucketCloudReposActionTest {
 
     assertThat(def.since()).isEqualTo("9.0");
     assertThat(def.isPost()).isFalse();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
     assertThat(def.params())
       .extracting(WebService.Param::key, WebService.Param::isRequired)
       .containsExactlyInAnyOrder(
@@ -209,8 +210,7 @@ public class SearchBitbucketCloudReposActionTest {
 
   private Repository getBBCRepo2() {
     Project project2 = new Project("PROJECT-UUID-TWO", "projectKey2", "projectName2");
-    Repository repo2 = new Repository("REPO-UUID-TWO", "repo-slug-2", "repoName2", project2, null);
-    return repo2;
+    return new Repository("REPO-UUID-TWO", "repo-slug-2", "repoName2", project2, null);
   }
 
 }
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsActionTest.java
index b5a88fbf067..2b2f3b43b45 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/ListBitbucketServerProjectsActionTest.java
@@ -151,6 +151,7 @@ public class ListBitbucketServerProjectsActionTest {
 
     assertThat(def.since()).isEqualTo("8.2");
     assertThat(def.isPost()).isFalse();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
     assertThat(def.params())
       .extracting(WebService.Param::key, WebService.Param::isRequired)
       .containsExactlyInAnyOrder(tuple("almSetting", true));
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposActionTest.java
index 00fb2634aa4..3717cfd7167 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/bitbucketserver/SearchBitbucketServerReposActionTest.java
@@ -240,6 +240,7 @@ public class SearchBitbucketServerReposActionTest {
 
     assertThat(def.since()).isEqualTo("8.2");
     assertThat(def.isPost()).isFalse();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
     assertThat(def.params())
       .extracting(WebService.Param::key, WebService.Param::isRequired)
       .containsExactlyInAnyOrder(
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/github/ListGithubOrganizationsActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/github/ListGithubOrganizationsActionTest.java
index 8119cb08eb0..9639ff1da61 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/github/ListGithubOrganizationsActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/almintegration/ws/github/ListGithubOrganizationsActionTest.java
@@ -30,6 +30,7 @@ import org.sonar.alm.client.github.GithubApplicationClientImpl;
 import org.sonar.alm.client.github.security.UserAccessToken;
 import org.sonar.api.config.internal.Encryption;
 import org.sonar.api.config.internal.Settings;
+import org.sonar.api.server.ws.WebService;
 import org.sonar.api.utils.System2;
 import org.sonar.db.DbTester;
 import org.sonar.db.alm.pat.AlmPatDto;
@@ -258,6 +259,19 @@ public class ListGithubOrganizationsActionTest {
       .isEqualTo(pat.getPersonalAccessToken());
   }
 
+  @Test
+  public void definition() {
+    WebService.Action def = ws.getDef();
+
+    assertThat(def.since()).isEqualTo("8.4");
+    assertThat(def.isPost()).isFalse();
+    assertThat(def.isInternal()).isTrue();
+    assertThat(def.responseExampleFormat()).isEqualTo("json");
+    assertThat(def.params())
+      .extracting(WebService.Param::key, WebService.Param::isRequired)
+      .containsExactlyInAnyOrder(tuple("p", false), tuple("ps", false), tuple("almSetting", true), tuple("token", false));
+  }
+
   private void setupGhOrganizations(AlmSettingDto almSetting, String pat) {
     when(appClient.listOrganizations(eq(almSetting.getUrl()), argThat(token -> token.getValue().equals(pat)), eq(1), eq(100)))
       .thenReturn(new GithubApplicationClient.Organizations()
diff --git a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/projectdump/ws/StatusActionTest.java b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/projectdump/ws/StatusActionTest.java
index 77398253609..f9f866ef065 100644
--- a/server/sonar-webserver-webapi/src/test/java/org/sonar/server/projectdump/ws/StatusActionTest.java
+++ b/server/sonar-webserver-webapi/src/test/java/org/sonar/server/projectdump/ws/StatusActionTest.java
@@ -30,6 +30,7 @@ import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
 import org.sonar.api.config.Configuration;
+import org.sonar.api.server.ws.WebService;
 import org.sonar.api.utils.System2;
 import org.sonar.api.web.UserRole;
 import org.sonar.core.util.Slug;
@@ -49,6 +50,7 @@ import org.sonar.server.ws.WsActionTester;
 import static java.util.Comparator.reverseOrder;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.assertj.core.api.Assertions.tuple;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 import static org.sonar.api.resources.Qualifiers.PROJECT;
@@ -97,6 +99,23 @@ public class StatusActionTest {
   }
 
   @Test
+  public void definition() {
+    WebService.Action definition = underTest.getDef();
+
+    assertThat(definition.key()).isEqualTo("status");
+    assertThat(definition.isPost()).isFalse();
+    assertThat(definition.description()).isNotEmpty();
+    assertThat(definition.since()).isEqualTo("1.0");
+    assertThat(definition.isInternal()).isTrue();
+    assertThat(definition.responseExampleFormat()).isEqualTo("json");
+    assertThat(definition.params())
+      .extracting(WebService.Param::key, WebService.Param::isRequired)
+      .containsExactlyInAnyOrder(
+        tuple("id", false),
+        tuple("key", false));
+  }
+
+  @Test
   public void fails_with_BRE_if_no_param_is_provided() {
     assertThatThrownBy(() -> underTest.newRequest().execute())
       .isInstanceOf(BadRequestException.class)