SONAR-5111 Complete api/users WS documentations

5 files changed, 228 insertions, 1 deletions

diff --git a/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java b/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
index 3c74627ec06..bc097e24dc0 100644
--- a/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
+++ b/sonar-server/src/main/java/org/sonar/server/component/ws/ProjectsWs.java
@@ -43,7 +43,6 @@ public class ProjectsWs implements WebService {
     WebService.NewAction action = controller.createAction("index")
       .setDescription("Search for projects")
       .setSince("2.10")
-      .setPost(true)
       .setHandler(RailsHandler.INSTANCE)
       .setResponseExample(Resources.getResource(this.getClass(), "example-index.json"));
 
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 392cc06c452..1315687174d 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
@@ -137,6 +137,7 @@ import org.sonar.server.ui.PageDecorations;
 import org.sonar.server.ui.Views;
 import org.sonar.server.updatecenter.ws.UpdateCenterWs;
 import org.sonar.server.user.*;
+import org.sonar.server.user.ws.UsersWs;
 import org.sonar.server.util.*;
 import org.sonar.server.ws.ListingWs;
 import org.sonar.server.ws.WebServiceEngine;
@@ -358,6 +359,7 @@ class ServerComponents {
     pico.addSingleton(NewUserNotifier.class);
     pico.addSingleton(DefaultUserFinder.class);
     pico.addSingleton(DefaultUserService.class);
+    pico.addSingleton(UsersWs.class);
 
     // groups
     pico.addSingleton(GroupMembershipService.class);
diff --git a/sonar-server/src/main/java/org/sonar/server/user/ws/UsersWs.java b/sonar-server/src/main/java/org/sonar/server/user/ws/UsersWs.java
new file mode 100644
index 00000000000..531c6466450
--- /dev/null
+++ b/sonar-server/src/main/java/org/sonar/server/user/ws/UsersWs.java
@@ -0,0 +1,125 @@
+/*
+ * 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.user.ws;
+
+import com.google.common.io.Resources;
+import org.sonar.api.server.ws.RailsHandler;
+import org.sonar.api.server.ws.WebService;
+
+public class UsersWs implements WebService {
+
+  @Override
+  public void define(Context context) {
+    NewController controller = context.createController("api/users")
+      .setSince("3.6")
+      .setDescription("Users management");
+
+    defineSearchAction(controller);
+    defineCreateAction(controller);
+    defineUpdateAction(controller);
+    defineDeactivateAction(controller);
+
+    controller.done();
+  }
+
+  private void defineSearchAction(NewController controller) {
+    NewAction action = controller.createAction("search")
+      .setDescription("Get a list of users")
+      .setSince("3.6")
+      .setHandler(RailsHandler.INSTANCE)
+      .setResponseExample(Resources.getResource(this.getClass(), "example-search.json"));
+
+    action.createParam("includeDeactivated")
+      .setDescription("Include deactivated users")
+      .setDefaultValue("false")
+      .setBooleanPossibleValues();
+
+    action.createParam("logins")
+      .setDescription("Comma-separated list of user logins")
+      .setExampleValue("admin,sbrandhof");
+  }
+
+  private void defineCreateAction(NewController controller) {
+    NewAction action = controller.createAction("create")
+      .setDescription("Create a user. Requires Administer System permission")
+      .setSince("3.7")
+      .setPost(true)
+      .setHandler(RailsHandler.INSTANCE);
+
+    action.createParam("login")
+      .setDescription("User login")
+      .setRequired(true)
+      .setExampleValue("myuser");
+
+    action.createParam("password")
+      .setDescription("User password")
+      .setRequired(true)
+      .setExampleValue("mypassword");
+
+    action.createParam("password_confirmation")
+      .setDescription("Must be the same value as \"password\"")
+      .setRequired(true)
+      .setExampleValue("mypassword");
+
+    action.createParam("name")
+      .setDescription("User name")
+      .setExampleValue("My Name");
+
+    action.createParam("email")
+      .setDescription("User email")
+      .setExampleValue("myname@email.com");
+  }
+
+  private void defineUpdateAction(NewController controller) {
+    NewAction action = controller.createAction("update")
+      .setDescription("Update a user. Requires Administer System permission")
+      .setSince("3.7")
+      .setPost(true)
+      .setHandler(RailsHandler.INSTANCE);
+
+    action.createParam("login")
+      .setDescription("User login")
+      .setRequired(true)
+      .setExampleValue("myuser");
+
+    action.createParam("name")
+      .setDescription("User name")
+      .setExampleValue("My New Name");
+
+    action.createParam("email")
+      .setDescription("User email")
+      .setExampleValue("mynewname@email.com");
+  }
+
+  private void defineDeactivateAction(NewController controller) {
+    NewAction action = controller.createAction("deactivate")
+      .setDescription("Deactivate a user. Requires Administer System permission")
+      .setSince("3.7")
+      .setPost(true)
+      .setHandler(RailsHandler.INSTANCE);
+
+    action.createParam("login")
+      .setDescription("User login")
+      .setRequired(true)
+      .setExampleValue("myuser");
+  }
+
+}
diff --git a/sonar-server/src/main/resources/org/sonar/server/user/ws/example-search.json b/sonar-server/src/main/resources/org/sonar/server/user/ws/example-search.json
new file mode 100644
index 00000000000..3cbb0005bcf
--- /dev/null
+++ b/sonar-server/src/main/resources/org/sonar/server/user/ws/example-search.json
@@ -0,0 +1,15 @@
+{
+  "users": [
+    {
+      "login": "fmallet",
+      "name": "Freddy Mallet",
+      "active": true,
+      "email": "f@m.com"
+    },
+    {
+      "login": "sbrandhof",
+      "name": "Simon",
+      "active": true
+    }
+  ]
+}
diff --git a/sonar-server/src/test/java/org/sonar/server/user/ws/UsersWsTest.java b/sonar-server/src/test/java/org/sonar/server/user/ws/UsersWsTest.java
new file mode 100644
index 00000000000..c9372f4e48c
--- /dev/null
+++ b/sonar-server/src/test/java/org/sonar/server/user/ws/UsersWsTest.java
@@ -0,0 +1,86 @@
+/*
+ * 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.user.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 UsersWsTest {
+
+  WebService.Controller controller;
+
+  @Before
+  public void setUp() throws Exception {
+    WsTester tester = new WsTester(new UsersWs());
+    controller = tester.controller("api/users");
+  }
+
+  @Test
+  public void define_controller() throws Exception {
+    assertThat(controller).isNotNull();
+    assertThat(controller.description()).isNotEmpty();
+    assertThat(controller.since()).isEqualTo("3.6");
+    assertThat(controller.actions()).hasSize(4);
+  }
+
+  @Test
+  public void define_search_action() throws Exception {
+    WebService.Action action = controller.action("search");
+    assertThat(action).isNotNull();
+    assertThat(action.isPost()).isFalse();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.responseExampleAsString()).isNotEmpty();
+    assertThat(action.params()).hasSize(2);
+  }
+
+  @Test
+  public void define_create_action() throws Exception {
+    WebService.Action action = controller.action("create");
+    assertThat(action).isNotNull();
+    assertThat(action.isPost()).isTrue();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.params()).hasSize(5);
+  }
+
+  @Test
+  public void define_update_action() throws Exception {
+    WebService.Action action = controller.action("update");
+    assertThat(action).isNotNull();
+    assertThat(action.isPost()).isTrue();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.params()).hasSize(3);
+  }
+
+  @Test
+  public void define_deactivate_action() throws Exception {
+    WebService.Action action = controller.action("deactivate");
+    assertThat(action).isNotNull();
+    assertThat(action.isPost()).isTrue();
+    assertThat(action.handler()).isInstanceOf(RailsHandler.class);
+    assertThat(action.params()).hasSize(1);
+  }
+
+}