more api documentation

src/main/java/com/commafeed/frontend/model/ProfileModificationRequest.java

@@ -4,11 +4,18 @@ import javax.xml.bind.annotation.XmlAccessType;
 import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlRootElement;
 
+import com.wordnik.swagger.annotations.ApiClass;
+import com.wordnik.swagger.annotations.ApiProperty;
+
 @XmlRootElement
 @XmlAccessorType(XmlAccessType.FIELD)
+@ApiClass("Profile modification request")
 public class ProfileModificationRequest {
-	
+
+	@ApiProperty(value = "changes email of the user, if specified")
 	private String email;
+
+	@ApiProperty(value = "changes password of the user, if specified")
 	private String password;
 
 	public String getEmail() {

src/main/java/com/commafeed/frontend/model/Subscription.java

@@ -6,16 +6,31 @@ import javax.xml.bind.annotation.XmlAccessType;
 import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlRootElement;
 
+import com.wordnik.swagger.annotations.ApiClass;
+import com.wordnik.swagger.annotations.ApiProperty;
+
 @SuppressWarnings("serial")
 @XmlRootElement
 @XmlAccessorType(XmlAccessType.FIELD)
+@ApiClass("User information")
 public class Subscription implements Serializable {
 
+	@ApiProperty(value = "subscription id", required = true)
 	private Long id;
+
+	@ApiProperty(value = "subscription name", required = true)
 	private String name;
+
+	@ApiProperty(value = "error message while fetching the feed", required = true)
 	private String message;
+
+	@ApiProperty(value = "error count", required = true)
 	private int errorCount;
+
+	@ApiProperty(value = "this subscription's feed url", required = true)
 	private String feedUrl;
+
+	@ApiProperty(value = "unread count", required = true)
 	private long unread;
 
 	public Long getId() {

src/main/java/com/commafeed/frontend/model/UserModel.java

@@ -6,16 +6,31 @@ import javax.xml.bind.annotation.XmlAccessType;
 import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlRootElement;
 
+import com.wordnik.swagger.annotations.ApiClass;
+import com.wordnik.swagger.annotations.ApiProperty;
+
 @SuppressWarnings("serial")
 @XmlRootElement
 @XmlAccessorType(XmlAccessType.FIELD)
+@ApiClass("User information")
 public class UserModel implements Serializable {
 
+	@ApiProperty(value = "user id", required = true)
 	private Long id;
+
+	@ApiProperty(value = "user name", required = true)
 	private String name;
+
+	@ApiProperty("user email, if any")
 	private String email;
+
+	@ApiProperty(value = "user password, never returned by the api")
 	private String password;
+
+	@ApiProperty(value = "account status")
 	private boolean enabled;
+
+	@ApiProperty(value = "user is admin")
 	private boolean admin;
 
 	public Long getId() {

src/main/java/com/commafeed/frontend/rest/resources/AdminMetricsREST.java

@@ -9,7 +9,7 @@ import com.commafeed.backend.model.UserRole.Role;
 import com.commafeed.frontend.SecurityCheck;
 
 @SecurityCheck(Role.ADMIN)
-@Path("admin/metrics")
+@Path("/admin/metrics")
 public class AdminMetricsREST extends AbstractREST {
 
 	@Inject

src/main/java/com/commafeed/frontend/rest/resources/AdminSettingsREST.java

@@ -9,23 +9,31 @@ import com.commafeed.backend.model.ApplicationSettings;
 import com.commafeed.backend.model.UserRole.Role;
 import com.commafeed.backend.services.ApplicationSettingsService;
 import com.commafeed.frontend.SecurityCheck;
+import com.google.common.base.Preconditions;
+import com.wordnik.swagger.annotations.Api;
+import com.wordnik.swagger.annotations.ApiOperation;
+import com.wordnik.swagger.annotations.ApiParam;
 
 @SecurityCheck(Role.ADMIN)
-@Path("admin/settings")
+@Path("/admin/settings")
+@Api(value = "/admin/settings", description = "Operations about application settings administration")
 public class AdminSettingsREST {
 
 	@Inject
 	ApplicationSettingsService applicationSettingsService;
 
-	@Path("get")
+	@Path("/get")
 	@GET
+	@ApiOperation(value = "Retrieve application settings", notes = "Retrieve application settings", responseClass = "com.commafeed.backend.model.ApplicationSettings")
 	public ApplicationSettings get() {
 		return applicationSettingsService.get();
 	}
 
-	@Path("save")
+	@Path("/save")
 	@POST
-	public void save(ApplicationSettings settings) {
+	@ApiOperation(value = "Save application settings", notes = "Save application settings")
+	public void save(@ApiParam(required = true) ApplicationSettings settings) {
+		Preconditions.checkNotNull(settings);
 		applicationSettingsService.save(settings);
 	}
 }

src/main/java/com/commafeed/frontend/rest/resources/AdminUsersREST.java

@@ -23,14 +23,19 @@ import com.commafeed.frontend.model.UserModel;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Maps;
 import com.google.common.collect.Sets;
+import com.wordnik.swagger.annotations.Api;
+import com.wordnik.swagger.annotations.ApiOperation;
+import com.wordnik.swagger.annotations.ApiParam;
 
 @SecurityCheck(Role.ADMIN)
-@Path("admin/users")
+@Path("/admin/users")
+@Api(value = "/admin/users", description = "Operations about application users administration")
 public class AdminUsersREST extends AbstractREST {
 
-	@Path("save")
+	@Path("/save")
 	@POST
-	public Response save(UserModel userModel) {
+	@ApiOperation(value = "Manually save or update a user", notes = "Manually save or update a user. If the id is not specified, a new user will be created")
+	public Response save(@ApiParam(required = true) UserModel userModel) {
 		Preconditions.checkNotNull(userModel);
 		Preconditions.checkNotNull(userModel.getName());
 
@@ -86,9 +91,12 @@ public class AdminUsersREST extends AbstractREST {
 
 	}
 
-	@Path("get")
+	@Path("/get")
 	@GET
-	public UserModel getUser(@QueryParam("id") Long id) {
+	@ApiOperation(value = "Get user information", notes = "Get user information", responseClass = "com.commafeed.frontend.model.UserModel")
+	public UserModel getUser(
+			@ApiParam(value = "user id", required = true) @QueryParam("id") Long id) {
+		Preconditions.checkNotNull(id);
 		User user = userDAO.findById(id);
 		UserModel userModel = new UserModel();
 		userModel.setId(user.getId());
@@ -102,8 +110,9 @@ public class AdminUsersREST extends AbstractREST {
 		return userModel;
 	}
 
-	@Path("getAll")
+	@Path("/getAll")
 	@GET
+	@ApiOperation(value = "Get all users", notes = "Get all users", responseClass = "List[com.commafeed.frontend.model.UserModel]")
 	public Collection<UserModel> getUsers() {
 		Map<Long, UserModel> users = Maps.newHashMap();
 		for (UserRole role : userRoleDAO.findAll()) {
@@ -124,9 +133,13 @@ public class AdminUsersREST extends AbstractREST {
 		return users.values();
 	}
 
-	@Path("delete")
+	@Path("/delete")
 	@GET
-	public Response delete(@QueryParam("id") Long id) {
+	@ApiOperation(value = "Delete a user", notes = "Delete a user, and all his subscriptions")
+	public Response delete(
+			@ApiParam(value = "user id", required = true) @QueryParam("id") Long id) {
+		Preconditions.checkNotNull(id);
+
 		User user = userDAO.findById(id);
 		if (user == null) {
 			return Response.status(Status.NOT_FOUND).build();
@@ -135,8 +148,8 @@ public class AdminUsersREST extends AbstractREST {
 			return Response.status(Status.FORBIDDEN)
 					.entity("You cannot delete the admin user.").build();
 		}
-		feedEntryStatusDAO.delete(feedEntryStatusDAO.findAll(user,
+		feedEntryStatusDAO.delete(feedEntryStatusDAO.findAll(user, false,
-				false, ReadingOrder.desc, false));
+				ReadingOrder.desc, false));
 		feedSubscriptionDAO.delete(feedSubscriptionDAO.findAll(user));
 		feedCategoryDAO.delete(feedCategoryDAO.findAll(user));
 		userSettingsDAO.delete(userSettingsDAO.findByUser(user));

src/main/java/com/commafeed/frontend/rest/resources/SessionREST.java

@@ -12,12 +12,17 @@ import com.commafeed.backend.model.UserRole;
 import com.commafeed.backend.model.UserRole.Role;
 import com.commafeed.frontend.model.ProfileModificationRequest;
 import com.commafeed.frontend.model.UserModel;
+import com.wordnik.swagger.annotations.Api;
+import com.wordnik.swagger.annotations.ApiOperation;
+import com.wordnik.swagger.annotations.ApiParam;
 
-@Path("session")
+@Path("/session")
+@Api(value = "/session", description = "Operations about user profile")
 public class SessionREST extends AbstractREST {
 
-	@Path("get")
+	@Path("/get")
 	@GET
+	@ApiOperation(value = "Retrieve user's profile", responseClass = "com.commafeed.frontend.model.UserModel")
 	public UserModel get() {
 		User user = getUser();
 		UserModel userModel = new UserModel();
@@ -33,9 +38,11 @@ public class SessionREST extends AbstractREST {
 		return userModel;
 	}
 
-	@Path("save")
+	@Path("/save")
 	@POST
-	public Response save(ProfileModificationRequest request) {
+	@ApiOperation(value = "Save user's profile")
+	public Response save(
+			@ApiParam(required = true) ProfileModificationRequest request) {
 		User user = getUser();
 		user.setEmail(request.getEmail());
 		if (StringUtils.isNotBlank(request.getPassword())) {

src/main/java/com/commafeed/frontend/rest/resources/SubscriptionsREST.java

@@ -41,7 +41,8 @@ public class SubscriptionsREST extends AbstractREST {
 	@GET
 	@Path("/feed/fetch")
 	@ApiOperation(value = "Fetch a feed", notes = "Fetch a feed by its url", responseClass = "com.commafeed.backend.model.Feed")
-	public Feed fetchFeed(@QueryParam("url") String url) {
+	public Feed fetchFeed(
+			@ApiParam(value = "the feed's url", required = true) @QueryParam("url") String url) {
 		Preconditions.checkNotNull(url);
 		url = StringUtils.trimToEmpty(url);
 		url = prependHttp(url);