diff --git a/src/main/java/com/commafeed/frontend/model/ProfileModificationRequest.java b/src/main/java/com/commafeed/frontend/model/ProfileModificationRequest.java index 4aa1dda7..2c1a7c1f 100644 --- a/src/main/java/com/commafeed/frontend/model/ProfileModificationRequest.java +++ b/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() { diff --git a/src/main/java/com/commafeed/frontend/model/Subscription.java b/src/main/java/com/commafeed/frontend/model/Subscription.java index 512e4f08..0eaaa190 100644 --- a/src/main/java/com/commafeed/frontend/model/Subscription.java +++ b/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() { diff --git a/src/main/java/com/commafeed/frontend/model/UserModel.java b/src/main/java/com/commafeed/frontend/model/UserModel.java index f6b92d7c..5fc82139 100644 --- a/src/main/java/com/commafeed/frontend/model/UserModel.java +++ b/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() { diff --git a/src/main/java/com/commafeed/frontend/rest/resources/AdminMetricsREST.java b/src/main/java/com/commafeed/frontend/rest/resources/AdminMetricsREST.java index 277275b1..cd10d4d9 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/AdminMetricsREST.java +++ b/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 diff --git a/src/main/java/com/commafeed/frontend/rest/resources/AdminSettingsREST.java b/src/main/java/com/commafeed/frontend/rest/resources/AdminSettingsREST.java index 4bbaf4f8..48dfc82a 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/AdminSettingsREST.java +++ b/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); } } diff --git a/src/main/java/com/commafeed/frontend/rest/resources/AdminUsersREST.java b/src/main/java/com/commafeed/frontend/rest/resources/AdminUsersREST.java index f8dcf685..f41f26f3 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/AdminUsersREST.java +++ b/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 getUsers() { Map 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, - false, ReadingOrder.desc, false)); + feedEntryStatusDAO.delete(feedEntryStatusDAO.findAll(user, false, + ReadingOrder.desc, false)); feedSubscriptionDAO.delete(feedSubscriptionDAO.findAll(user)); feedCategoryDAO.delete(feedCategoryDAO.findAll(user)); userSettingsDAO.delete(userSettingsDAO.findByUser(user)); diff --git a/src/main/java/com/commafeed/frontend/rest/resources/SessionREST.java b/src/main/java/com/commafeed/frontend/rest/resources/SessionREST.java index 1d8d1921..2e9825f9 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/SessionREST.java +++ b/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())) { 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 d9de9972..0a23b726 100644 --- a/src/main/java/com/commafeed/frontend/rest/resources/SubscriptionsREST.java +++ b/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);