From 3ab8abe5bdd97e897c8b3948b33d9d1e30b4335d Mon Sep 17 00:00:00 2001 From: Athou Date: Tue, 16 Apr 2013 12:36:18 +0200 Subject: [PATCH] more api documentation --- .../com/commafeed/frontend/model/Entries.java | 10 +- .../com/commafeed/frontend/model/Entry.java | 27 +++++ .../frontend/model/SubscriptionRequest.java | 9 ++ .../rest/resources/SubscriptionsREST.java | 102 +++++++++++------- src/main/webapp/js/directives.js | 4 +- src/main/webapp/js/services.js | 22 ++-- 6 files changed, 119 insertions(+), 55 deletions(-) diff --git a/src/main/java/com/commafeed/frontend/model/Entries.java b/src/main/java/com/commafeed/frontend/model/Entries.java index 8bbbfb98..709e25d1 100644 --- a/src/main/java/com/commafeed/frontend/model/Entries.java +++ b/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 entries = Lists.newArrayList(); public String getName() { diff --git a/src/main/java/com/commafeed/frontend/model/Entry.java b/src/main/java/com/commafeed/frontend/model/Entry.java index d750be8c..96041981 100644 --- a/src/main/java/com/commafeed/frontend/model/Entry.java +++ b/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() { diff --git a/src/main/java/com/commafeed/frontend/model/SubscriptionRequest.java b/src/main/java/com/commafeed/frontend/model/SubscriptionRequest.java index a00ea470..aeaaf67c 100644 --- a/src/main/java/com/commafeed/frontend/model/SubscriptionRequest.java +++ b/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() { diff --git a/src/main/java/com/commafeed/frontend/rest/resources/SubscriptionsREST.java b/src/main/java/com/commafeed/frontend/rest/resources/SubscriptionsREST.java index 91073bb9..bcbbe801 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/SubscriptionsREST.java +++ b/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") - @ApiOperation(value = "Search for entries", notes = "Look through title and content of entries by keywords", responseClass = "com.commafeed.frontend.model.Entries") + @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) { Preconditions.checkNotNull(url); @@ -56,8 +56,10 @@ public class SubscriptionsREST extends AbstractREST { } @POST - @Path("/subscribe") - public Response subscribe(SubscriptionRequest req) { + @Path("/feed/subscribe") + @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") - public Response unsubscribe(@QueryParam("id") Long subscriptionId) { + @Path("/feed/unsubscribe") + @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") - public Response rename(@QueryParam("type") Type type, - @QueryParam("id") Long id, @QueryParam("name") String name) { - if (type == Type.feed) { - FeedSubscription subscription = feedSubscriptionDAO.findById( - getUser(), id); - subscription.setTitle(name); - feedSubscriptionDAO.update(subscription); - } else if (type == Type.category) { - FeedCategory category = feedCategoryDAO.findById(getUser(), id); - category.setName(name); - feedCategoryDAO.update(category); - } + @Path("/feed/rename") + @ApiOperation(value = "Rename a subscription", notes = "Rename a feed subscription") + public Response rename( + @ApiParam(value = "subscription id", required = true) @QueryParam("id") Long id, + @ApiParam(value = "new name", required = true) @QueryParam("name") String name) { + FeedSubscription subscription = feedSubscriptionDAO.findById(getUser(), + id); + subscription.setTitle(name); + feedSubscriptionDAO.update(subscription); + return Response.ok(Status.OK).build(); } + @Path("/category/add") @GET - @Path("/collapse") - public Response collapse(@QueryParam("id") String id, - @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(); - } - - @Path("/addCategory") - @GET - public Response addCategory(@QueryParam("name") String name, - @QueryParam("parentId") String parentId) { + @ApiOperation(value = "Add a category", notes = "Add a new feed category") + public Response addCategory( + @ApiParam(value = "new name", required = true) @QueryParam("name") String name, + @ApiParam(value = "parent category id, if any") @QueryParam("parentId") String parentId) { Preconditions.checkNotNull(name); FeedCategory cat = new FeedCategory(); @@ -144,8 +133,10 @@ public class SubscriptionsREST extends AbstractREST { } @GET - @Path("/deleteCategory") - public Response deleteCategory(@QueryParam("id") Long id) { + @Path("/category/delete") + @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 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 categories = feedCategoryDAO.findAll(getUser()); diff --git a/src/main/webapp/js/directives.js b/src/main/webapp/js/directives.js index acbc3b27..65c0cc70 100644 --- a/src/main/webapp/js/directives.js +++ b/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({ - type : 'category', + SubscriptionService.renameCategory({ id : category.id, name : name }); diff --git a/src/main/webapp/js/services.js b/src/main/webapp/js/services.js index b2e55f94..6b3d5729 100644 --- a/src/main/webapp/js/services.js +++ b/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' } } };