more api documentation

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

@@ -17,19 +17,19 @@ import com.wordnik.swagger.annotations.ApiProperty;
 @ApiClass("List of entries with some metadata")
 public class Entries implements Serializable {
 
-	@ApiProperty("Name of the feed or the category requested")
+	@ApiProperty("name of the feed or the category requested")
 	private String name;
 
-	@ApiProperty("Error or warning message")
+	@ApiProperty("error or warning message")
 	private String message;
 
-	@ApiProperty("TImes the server tried to refresh the feed and failed")
+	@ApiProperty("times the server tried to refresh the feed and failed")
 	private int errorCount;
 
-	@ApiProperty("List generation Timestamp")
+	@ApiProperty("list generation Timestamp")
 	private long timestamp;
 
-	@ApiProperty("List of entries")
+	@ApiProperty("list of entries")
 	private List<Entry> entries = Lists.newArrayList();
 
 	public String getName() {

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

@@ -7,22 +7,49 @@ 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("Entry details")
 public class Entry implements Serializable {
 
+	@ApiProperty("entry id")
 	private String id;
+	
+	@ApiProperty("entry title")
 	private String title;
+	
+	@ApiProperty("entry content")
 	private String content;
+	
+	@ApiProperty("entry enclosure url, if any")
 	private String enclosureUrl;
+	
+	@ApiProperty("entry enclosure mime type, if any")
 	private String enclosureType;
+	
+	@ApiProperty("entry publication date")
 	private Date date;
+	
+	@ApiProperty("feed id")
 	private String feedId;
+	
+	@ApiProperty("feed name")
 	private String feedName;
+	
+	@ApiProperty("feed url")
 	private String feedUrl;
+	
+	@ApiProperty("entry url")
 	private String url;
+	
+	@ApiProperty("read sttaus")
 	private boolean read;
+	
+	@ApiProperty("starred status")
 	private boolean starred;
 
 	public String getId() {

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

@@ -6,13 +6,22 @@ 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("Subscription request")
 public class SubscriptionRequest implements Serializable {
 
+	@ApiProperty(value = "url of the feed", required = true)
 	private String url;
+
+	@ApiProperty(value = "name of the feed for the user", required = true)
 	private String title;
+
+	@ApiProperty(value = "id of the user category to place the feed in")
 	private String categoryId;
 
 	public String getUrl() {

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

@@ -28,18 +28,18 @@ import com.commafeed.backend.model.FeedSubscription;
 import com.commafeed.frontend.model.Category;
 import com.commafeed.frontend.model.Subscription;
 import com.commafeed.frontend.model.SubscriptionRequest;
-import com.commafeed.frontend.rest.resources.EntriesREST.Type;
 import com.google.common.base.Preconditions;
 import com.wordnik.swagger.annotations.Api;
 import com.wordnik.swagger.annotations.ApiOperation;
+import com.wordnik.swagger.annotations.ApiParam;
 
 @Path("/subscriptions")
 @Api(value = "/subscriptions", description = "Operations about user feed subscriptions")
 public class SubscriptionsREST extends AbstractREST {
 
 	@GET
-	@Path("/fetch")
+	@Path("/feed/fetch")
-	@ApiOperation(value = "Search for entries", notes = "Look through title and content of entries by keywords", responseClass = "com.commafeed.frontend.model.Entries")
+	@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) {
 		Preconditions.checkNotNull(url);
 
@@ -56,8 +56,10 @@ public class SubscriptionsREST extends AbstractREST {
 	}
 
 	@POST
-	@Path("/subscribe")
+	@Path("/feed/subscribe")
-	public Response subscribe(SubscriptionRequest req) {
+	@ApiOperation(value = "Subscribe to a feed", notes = "Subscribe to a feed")
+	public Response subscribe(
+			@ApiParam(value = "subscription request", required = true) SubscriptionRequest req) {
 		Preconditions.checkNotNull(req);
 		Preconditions.checkNotNull(req.getTitle());
 		Preconditions.checkNotNull(req.getUrl());
@@ -82,8 +84,10 @@ public class SubscriptionsREST extends AbstractREST {
 	}
 
 	@GET
-	@Path("/unsubscribe")
+	@Path("/feed/unsubscribe")
-	public Response unsubscribe(@QueryParam("id") Long subscriptionId) {
+	@ApiOperation(value = "Unsubscribe to a feed", notes = "Unsubscribe to a feed")
+	public Response unsubscribe(
+			@ApiParam(value = "subscription id", required = true) @QueryParam("id") Long subscriptionId) {
 		FeedSubscription sub = feedSubscriptionDAO.findById(getUser(),
 				subscriptionId);
 		if (sub != null) {
@@ -95,40 +99,25 @@ public class SubscriptionsREST extends AbstractREST {
 	}
 
 	@GET
-	@Path("/rename")
+	@Path("/feed/rename")
-	public Response rename(@QueryParam("type") Type type,
+	@ApiOperation(value = "Rename a subscription", notes = "Rename a feed subscription")
-			@QueryParam("id") Long id, @QueryParam("name") String name) {
+	public Response rename(
-		if (type == Type.feed) {
+			@ApiParam(value = "subscription id", required = true) @QueryParam("id") Long id,
-			FeedSubscription subscription = feedSubscriptionDAO.findById(
+			@ApiParam(value = "new name", required = true) @QueryParam("name") String name) {
-					getUser(), id);
+		FeedSubscription subscription = feedSubscriptionDAO.findById(getUser(),
-			subscription.setTitle(name);
+				id);
-			feedSubscriptionDAO.update(subscription);
+		subscription.setTitle(name);
-		} else if (type == Type.category) {
+		feedSubscriptionDAO.update(subscription);
-			FeedCategory category = feedCategoryDAO.findById(getUser(), id);
+
-			category.setName(name);
-			feedCategoryDAO.update(category);
-		}
 		return Response.ok(Status.OK).build();
 	}
 
+	@Path("/category/add")
 	@GET
-	@Path("/collapse")
+	@ApiOperation(value = "Add a category", notes = "Add a new feed category")
-	public Response collapse(@QueryParam("id") String id,
+	public Response addCategory(
-			@QueryParam("collapse") boolean collapse) {
+			@ApiParam(value = "new name", required = true) @QueryParam("name") String name,
-		Preconditions.checkNotNull(id);
+			@ApiParam(value = "parent category id, if any") @QueryParam("parentId") String parentId) {
-		if (!EntriesREST.ALL.equals(id)) {
-			FeedCategory category = feedCategoryDAO.findById(getUser(),
-					Long.valueOf(id));
-			category.setCollapsed(collapse);
-			feedCategoryDAO.update(category);
-		}
-		return Response.ok(Status.OK).build();
-	}
-
-	@Path("/addCategory")
-	@GET
-	public Response addCategory(@QueryParam("name") String name,
-			@QueryParam("parentId") String parentId) {
 		Preconditions.checkNotNull(name);
 
 		FeedCategory cat = new FeedCategory();
@@ -144,8 +133,10 @@ public class SubscriptionsREST extends AbstractREST {
 	}
 
 	@GET
-	@Path("/deleteCategory")
+	@Path("/category/delete")
-	public Response deleteCategory(@QueryParam("id") Long id) {
+	@ApiOperation(value = "Delete a category", notes = "Delete an existing feed category")
+	public Response deleteCategory(
+			@ApiParam(value = "category id", required = true) @QueryParam("id") Long id) {
 		FeedCategory cat = feedCategoryDAO.findById(getUser(), id);
 		if (cat != null) {
 			List<FeedSubscription> subs = feedSubscriptionDAO.findByCategory(
@@ -161,9 +152,40 @@ public class SubscriptionsREST extends AbstractREST {
 		}
 	}
 
+	@GET
+	@Path("/category/rename")
+	@ApiOperation(value = "Rename a category", notes = "Rename an existing feed category")
+	public Response renameCategory(
+			@ApiParam(value = "category id", required = true) @QueryParam("id") Long id,
+			@ApiParam(value = "new name", required = true) @QueryParam("name") String name) {
+
+		FeedCategory category = feedCategoryDAO.findById(getUser(), id);
+		category.setName(name);
+		feedCategoryDAO.update(category);
+
+		return Response.ok(Status.OK).build();
+	}
+
+	@GET
+	@Path("/category/collapse")
+	@ApiOperation(value = "Collapse a category", notes = "Save collapsed or expanded status for a category")
+	public Response collapse(
+			@ApiParam(value = "category id", required = true) @QueryParam("id") String id,
+			@ApiParam(value = "true if collapsed", required = true) @QueryParam("collapse") boolean collapse) {
+		Preconditions.checkNotNull(id);
+		if (!EntriesREST.ALL.equals(id)) {
+			FeedCategory category = feedCategoryDAO.findById(getUser(),
+					Long.valueOf(id));
+			category.setCollapsed(collapse);
+			feedCategoryDAO.update(category);
+		}
+		return Response.ok(Status.OK).build();
+	}
+
 	@POST
 	@Path("/import")
 	@Consumes(MediaType.MULTIPART_FORM_DATA)
+	@ApiOperation(value = "OPML Import", notes = "Import an OPML file, posted as a FORM with the 'file' name")
 	public Response importOpml() {
 		try {
 			FileItemFactory factory = new DiskFileItemFactory(1000000, null);
@@ -184,6 +206,8 @@ public class SubscriptionsREST extends AbstractREST {
 	}
 
 	@GET
+	@Path("/get")
+	@ApiOperation(value = "Get feed subscriptions", notes = "Get all subscriptions of the user", responseClass = "com.commafeed.frontend.model.Category")
 	public Category getSubscriptions() {
 
 		List<FeedCategory> categories = feedCategoryDAO.findAll(getUser());

src/main/webapp/js/directives.js

@@ -114,7 +114,6 @@ module.directive('category', function($compile) {
 				if (name && name != feed.name) {
 					feed.name = name;
 					SubscriptionService.rename({
-						type : 'feed',
 						id : feed.id,
 						name : name
 					});
@@ -125,8 +124,7 @@ module.directive('category', function($compile) {
 				var name = window.prompt('Rename category: ', category.name);
 				if (name && name != category.name) {
 					category.name = name;
-					SubscriptionService.rename({
+					SubscriptionService.renameCategory({
-						type : 'category',
 						id : category.id,
 						name : name
 					});

src/main/webapp/js/services.js

@@ -42,49 +42,55 @@ module.factory('SubscriptionService', function($resource, $http) {
 		fetch : {
 			method : 'GET',
 			params : {
-				_method : 'fetch'
+				_method : 'feed/fetch'
 			}
 		},
 		get : {
 			method : 'GET',
 			params : {
-				_method : ''
+				_method : 'get'
 			}
 		},
 		subscribe : {
 			method : 'POST',
 			params : {
-				_method : 'subscribe'
+				_method : 'feed/subscribe'
 			}
 		},
 		unsubscribe : {
 			method : 'GET',
 			params : {
-				_method : 'unsubscribe'
+				_method : 'feed/unsubscribe'
 			}
 		},
 		rename : {
 			method : 'GET',
 			params : {
-				_method : 'rename'
+				_method : 'feed/rename'
 			}
 		},
 		collapse : {
 			method : 'GET',
 			params : {
-				_method : 'collapse'
+				_method : 'category/collapse'
 			}
 		},
 		addCategory : {
 			method : 'GET',
 			params : {
-				_method : 'addCategory'
+				_method : 'category/add'
 			}
 		},
 		deleteCategory : {
 			method : 'GET',
 			params : {
-				_method : 'deleteCategory'
+				_method : 'category/delete'
+			}
+		},
+		renameCategory : {
+			method : 'GET',
+			params : {
+				_method : 'category/rename'
 			}
 		}
 	};