improve rest api documentation of Authentication, ChangePassword, Cipher, Group, Key and Plugin resource

scm-webapp/src/main/java/sonia/scm/api/rest/resources/AuthenticationResource.java

@@ -41,6 +41,8 @@ import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableList.Builder;
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
 
 import org.apache.shiro.SecurityUtils;
@@ -78,11 +80,9 @@ import sonia.scm.util.HttpUtil;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
-import javax.servlet.http.Cookie;
 
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
-import javax.servlet.http.HttpSession;
 
 import javax.ws.rs.DefaultValue;
 import javax.ws.rs.FormParam;
@@ -100,7 +100,8 @@ import javax.xml.bind.annotation.XmlRootElement;
 import sonia.scm.security.XsrfCookies;
 
 /**
- *
+ * Authentication related RESTful Web Service endpoint.
+ * 
  * @author Sebastian Sdorra
  */
 @Singleton
@@ -152,15 +153,8 @@ public class AuthenticationResource
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Authenticate a user and return the state of the application.<br />
+   * Authenticate a user and return the state of the application.
-   * <br />
+   * 
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>400 bad request, required parameter is missing.</li>
-   *   <li>401 unauthorized, the specified username or password is wrong</li>
-   *   <li>500 internal server error</li>
-   * </ul>
-   *
    * @param request the current http request
    * @param username the username for the authentication
    * @param password the password for the authentication
@@ -171,6 +165,12 @@ public class AuthenticationResource
   @POST
   @Path("login")
   @TypeHint(ScmState.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, required parameter is missing"),
+    @ResponseCode(code = 401, condition = "unauthorized, the specified username or password is wrong"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   public Response authenticate(@Context HttpServletRequest request,
     @FormParam("username") String username,
     @FormParam("password") String password, @FormParam("rememberMe")
@@ -243,13 +243,7 @@ public class AuthenticationResource
   }
 
   /**
-   * Logout the current user. Returns the current state of the application,
+   * Logout the current user. Returns the current state of the application, if public access is enabled.
-   * if public access is enabled.<br />
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param request the current http request
    * @param response the current http response
@@ -259,6 +253,10 @@ public class AuthenticationResource
   @GET
   @Path("logout")
   @TypeHint(ScmState.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   public Response logout(@Context HttpServletRequest request,
     @Context HttpServletResponse response)
   {
@@ -287,16 +285,8 @@ public class AuthenticationResource
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * This method is an alias of the
+   * This method is an alias of the {@link #getState(HttpServletRequest)} method.
-   * {@link #getState(javax.servlet.http.HttpServletRequest)} method.
+   * The only difference between the methods, is that this one could not be used with basic authentication.
-   * The only difference between the methods,
-   * is that this one could not be used with basic authentication.<br />
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>401 unauthorized, user is not authenticated and public access is disabled.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param request the current http request
    *
@@ -305,19 +295,18 @@ public class AuthenticationResource
   @GET
   @Path("state")
   @TypeHint(ScmState.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 401, condition = "unauthorized, user is not authenticated and public access is disabled"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   public Response getCurrentState(@Context HttpServletRequest request)
   {
     return getState(request);
   }
 
   /**
-   * Returns the current state of the application.<br />
+   * Returns the current state of the application.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>401 unauthorized, user is not authenticated and public access is disabled.</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param request the current http request
    *
@@ -325,6 +314,11 @@ public class AuthenticationResource
    */
   @GET
   @TypeHint(ScmState.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 401, condition = "unauthorized, user is not authenticated and public access is disabled"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   public Response getState(@Context HttpServletRequest request)
   {
     Response response;
@@ -361,28 +355,12 @@ public class AuthenticationResource
 
   //~--- methods --------------------------------------------------------------
 
-  /**
-   * Method description
-   *
-   *
-   * @return
-   */
   private ScmState createAnonymousState()
   {
     return createState(SCMContext.ANONYMOUS, Collections.EMPTY_LIST,
       Collections.EMPTY_LIST, Collections.EMPTY_LIST);
   }
 
-  /**
-   * Method description
-   *
-   *
-   * @param securityContext
-   *
-   * @param subject
-   *
-   * @return
-   */
   private ScmState createState(Subject subject)
   {
     PrincipalCollection collection = subject.getPrincipals();
@@ -410,17 +388,6 @@ public class AuthenticationResource
     return createState(user, groups.getCollection(), builder.build(), ap);
   }
 
-  /**
-   * Method description
-   *
-   *
-   * @param user
-   * @param groups
-   * @param assignedPermissions
-   * @param availablePermissions
-   *
-   * @return
-   */
   private ScmState createState(User user, Collection<String> groups,
     List<String> assignedPermissions,
     List<PermissionDescriptor> availablePermissions)
@@ -431,17 +398,6 @@ public class AuthenticationResource
       availablePermissions);
   }
 
-  /**
-   * Method description
-   *
-   *
-   * @param request
-   * @param ex
-   * @param status
-   * @param failure
-   *
-   * @return
-   */
   private Response handleFailedAuthentication(HttpServletRequest request,
     AuthenticationException ex, Response.Status status,
     WUIAuthenticationFailure failure)

scm-webapp/src/main/java/sonia/scm/api/rest/resources/ChangePasswordResource.java

@@ -36,6 +36,8 @@ package sonia.scm.api.rest.resources;
 //~--- non-JDK imports --------------------------------------------------------
 
 import com.google.inject.Inject;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
 
 import org.apache.shiro.SecurityUtils;
@@ -66,7 +68,8 @@ import javax.ws.rs.core.Response;
 import sonia.scm.security.Role;
 
 /**
- *
+ * Resource to change the password of the authenticated user.
+ * 
  * @author Sebastian Sdorra
  */
 @Path("action/change-password")
@@ -98,14 +101,7 @@ public class ChangePasswordResource
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Changes the password of the current user.<br />
+   * Changes the password of the current user.
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>400 bad request, the old password is not correct</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param oldPassword old password of the current user
    * @param newPassword new password for the current user
@@ -117,6 +113,11 @@ public class ChangePasswordResource
    */
   @POST
   @TypeHint(RestActionResult.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 400, condition = "bad request, the old password is not correct"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Response changePassword(@FormParam("old-password") String oldPassword,
     @FormParam("new-password") String newPassword)

scm-webapp/src/main/java/sonia/scm/api/rest/resources/CipherResource.java

@@ -35,6 +35,8 @@ package sonia.scm.api.rest.resources;
 
 import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 import org.apache.shiro.SecurityUtils;
 
@@ -60,12 +62,7 @@ public class CipherResource
 
   /**
    * Encrypts the request body and returns an encrypted string. This method can
-   * only executed with administration privileges.<br />
+   * only executed with administration privileges.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param value value to encrypt
    *
@@ -73,6 +70,10 @@ public class CipherResource
    */
   @POST
   @Path("encrypt")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces(MediaType.TEXT_PLAIN)
   public String encrypt(String value)
   {

scm-webapp/src/main/java/sonia/scm/api/rest/resources/GroupResource.java

@@ -37,6 +37,9 @@ package sonia.scm.api.rest.resources;
 
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
 
 import org.apache.shiro.SecurityUtils;
@@ -68,7 +71,8 @@ import javax.ws.rs.core.Response;
 import javax.ws.rs.core.UriInfo;
 
 /**
- *
+ * RESTful Web Service Resource to manage groups and their members.
+ * 
  * @author Sebastian Sdorra
  */
 @Path("groups")
@@ -99,15 +103,7 @@ public class GroupResource
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Creates a new group.<br />
+   * Creates a new group. <strong>Note:</strong> This method requires admin privileges.
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 create success</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param uriInfo current uri informations
    * @param group the group to be created
@@ -115,6 +111,14 @@ public class GroupResource
    * @return
    */
   @POST
+  @StatusCodes({
+    @ResponseCode(code = 201, condition = "create success", additionalHeaders = {
+      @ResponseHeader(name = "Location", description = "uri to the created group")
+    }),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
   @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   @Override
   public Response create(@Context UriInfo uriInfo, Group group)
@@ -123,15 +127,7 @@ public class GroupResource
   }
 
   /**
-   * Deletes a group.<br />
+   * Deletes a group. <strong>Note:</strong> This method requires admin privileges.
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *  <li>201 delete success</li>
-   *  <li>403 forbidden, the current user has no admin privileges</li>
-   *  <li>500 internal server error</li>
-   * </ul>
    *
    * @param name the name of the group to delete.
    *
@@ -139,6 +135,12 @@ public class GroupResource
    */
   @DELETE
   @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "delete success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
   @Override
   public Response delete(@PathParam("id") String name)
   {
@@ -146,15 +148,7 @@ public class GroupResource
   }
 
   /**
-   * Modifies the given group.<br />
+   * Modifies the given group. <strong>Note:</strong> This method requires admin privileges.
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>201 update successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param uriInfo current uri informations
    * @param name name of the group to be modified
@@ -164,6 +158,12 @@ public class GroupResource
    */
   @PUT
   @Path("{id}")
+  @StatusCodes({
+    @ResponseCode(code = 204, condition = "update success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
   @Consumes({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   @Override
   public Response update(@Context UriInfo uriInfo,
@@ -175,16 +175,7 @@ public class GroupResource
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Returns a group.<br />
+   * Fetches a group by its name or id. <strong>Note:</strong> This method requires admin privileges.
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>404 not found, no group with the specified id/name available</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param request the current request
    * @param id the id/name of the group
@@ -194,6 +185,12 @@ public class GroupResource
   @GET
   @Path("{id}")
   @TypeHint(Group.class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 404, condition = "not found, no group with the specified id/name available"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   @Override
   public Response get(@Context Request request, @PathParam("id") String id)
@@ -213,15 +210,7 @@ public class GroupResource
   }
 
   /**
-   * Returns all groups.<br />
+   * Returns all groups. <strong>Note:</strong> This method requires admin privileges.
-   * This method requires admin privileges.<br />
-   * <br />
-   * Status codes:
-   * <ul>
-   *   <li>200 get successful</li>
-   *   <li>403 forbidden, the current user has no admin privileges</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param request the current request
    * @param start the start value for paging
@@ -234,6 +223,11 @@ public class GroupResource
   @GET
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   @TypeHint(Group[].class)
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 403, condition = "forbidden, the current user has no admin privileges"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Override
   public Response getAll(@Context Request request, @DefaultValue("0")
   @QueryParam("start") int start, @DefaultValue("-1")
@@ -246,14 +240,6 @@ public class GroupResource
 
   //~--- methods --------------------------------------------------------------
 
-  /**
-   * Method description
-   *
-   *
-   * @param items
-   *
-   * @return
-   */
   @Override
   protected GenericEntity<Collection<Group>> createGenericEntity(
     Collection<Group> items)
@@ -264,26 +250,12 @@ public class GroupResource
 
   //~--- get methods ----------------------------------------------------------
 
-  /**
-   * Method description
-   *
-   *
-   * @param group
-   *
-   * @return
-   */
   @Override
   protected String getId(Group group)
   {
     return group.getName();
   }
 
-  /**
-   * Method description
-   *
-   *
-   * @return
-   */
   @Override
   protected String getPathPart()
   {

scm-webapp/src/main/java/sonia/scm/api/rest/resources/KeyResource.java

@@ -34,6 +34,8 @@ package sonia.scm.api.rest.resources;
 //~--- non-JDK imports --------------------------------------------------------
 
 import com.google.inject.Inject;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 
 import org.apache.shiro.SecurityUtils;
 
@@ -72,17 +74,15 @@ public class KeyResource
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Generates a unique key. This method can only executed with administration
+   * Generates a unique key. <strong>Note:</strong> This method can only executed with administration privileges.
-   * privileges.<br />
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return unique key
    */
   @GET
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces(MediaType.TEXT_PLAIN)
   public String generateKey()
   {

scm-webapp/src/main/java/sonia/scm/api/rest/resources/PluginResource.java

@@ -53,6 +53,9 @@ import sonia.scm.plugin.PluginInformationComparator;
 //~--- JDK imports ------------------------------------------------------------
 
 import com.sun.jersey.multipart.FormDataParam;
+import com.webcohesion.enunciate.metadata.rs.ResponseCode;
+import com.webcohesion.enunciate.metadata.rs.StatusCodes;
+import com.webcohesion.enunciate.metadata.rs.TypeHint;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -73,7 +76,8 @@ import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.Status;
 
 /**
- *
+ * RESTful Web Service Endpoint to manage plugins.
+ * 
  * @author Sebastian Sdorra
  */
 @Singleton
@@ -104,13 +108,7 @@ public class PluginResource
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Installs a plugin from a package.<br />
+   * Installs a plugin from a package.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>412 precondition failed</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param uploadedInputStream
    * @return
@@ -119,6 +117,11 @@ public class PluginResource
    */
   @POST
   @Path("install-package")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 412, condition = "precondition failed"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Consumes(MediaType.MULTIPART_FORM_DATA)
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Response install(
@@ -150,35 +153,30 @@ public class PluginResource
   }
 
   /**
-   * Installs a plugin.<br />
+   * Installs a plugin.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param id id of the plugin to be installed
    *
    * @return
    */
   @POST
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
+  @TypeHint(TypeHint.NO_CONTENT.class)
   @Path("install/{id}")
   public Response install(@PathParam("id") String id)
   {
     pluginManager.install(id);
 
+    // TODO should return 204 no content
     return Response.ok().build();
   }
 
   /**
    * Installs a plugin from a package. This method is a workaround for ExtJS
-   * file upload, which requires text/html as content-type.<br />
+   * file upload, which requires text/html as content-type.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>412 precondition failed</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param uploadedInputStream
    * @return
@@ -187,6 +185,11 @@ public class PluginResource
    */
   @POST
   @Path("install-package.html")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 412, condition = "precondition failed"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Consumes(MediaType.MULTIPART_FORM_DATA)
   @Produces(MediaType.TEXT_HTML)
   public Response installFromUI(
@@ -197,60 +200,62 @@ public class PluginResource
   }
 
   /**
-   * Uninstalls a plugin.<br />
+   * Uninstalls a plugin.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param id id of the plugin to be uninstalled
    *
    * @return
    */
   @POST
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Path("uninstall/{id}")
   public Response uninstall(@PathParam("id") String id)
   {
     pluginManager.uninstall(id);
 
+    // TODO should return 204 content
+    // consider to do a uninstall with a delete
     return Response.ok().build();
   }
 
   /**
-   * Updates a plugin.<br />
+   * Updates a plugin.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @param id id of the plugin to be updated
    *
    * @return
    */
   @POST
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Path("update/{id}")
   public Response update(@PathParam("id") String id)
   {
     pluginManager.update(id);
 
+    // TODO should return 204 content
+    // consider to do an update with a put
+    
     return Response.ok().build();
   }
 
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Returns all plugins.<br />
+   * Returns all plugins.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return all plugins
    */
   @GET
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Collection<PluginInformation> getAll()
   {
@@ -258,17 +263,16 @@ public class PluginResource
   }
 
   /**
-   * Returns all available plugins.<br />
+   * Returns all available plugins.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return all available plugins
    */
   @GET
   @Path("available")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Collection<PluginInformation> getAvailable()
   {
@@ -276,17 +280,16 @@ public class PluginResource
   }
 
   /**
-   * Returns all plugins which are available for update.<br />
+   * Returns all plugins which are available for update.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return all plugins which are available for update
    */
   @GET
   @Path("updates")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Collection<PluginInformation> getAvailableUpdates()
   {
@@ -294,17 +297,16 @@ public class PluginResource
   }
 
   /**
-   * Returns all installed plugins.<br />
+   * Returns all installed plugins.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return all installed plugins
    */
   @GET
   @Path("installed")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Collection<PluginInformation> getInstalled()
   {
@@ -312,17 +314,16 @@ public class PluginResource
   }
 
   /**
-   * Returns all plugins for the overview.<br />
+   * Returns all plugins for the overview.
-   * <br />
-   * <ul>
-   *   <li>200 success</li>
-   *   <li>500 internal server error</li>
-   * </ul>
    *
    * @return all plugins for the overview
    */
   @GET
   @Path("overview")
+  @StatusCodes({
+    @ResponseCode(code = 200, condition = "success"),
+    @ResponseCode(code = 500, condition = "internal server error")
+  })
   @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
   public Collection<PluginInformation> getOverview()
   {