Commit 5d9b1807 authored by ma1uta's avatar ma1uta

Added swagger annotations to the filter api.

parent 6ea26571
......@@ -16,9 +16,16 @@
package io.github.ma1uta.matrix.client.api;
import static io.github.ma1uta.matrix.client.api.FilterApi.PATH;
import io.github.ma1uta.matrix.Secured;
import io.github.ma1uta.matrix.client.model.filter.FilterData;
import io.github.ma1uta.matrix.client.model.filter.FilterResponse;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
......@@ -38,16 +45,23 @@ import javax.ws.rs.core.SecurityContext;
* <p/>
* <a href="https://matrix.org/docs/spec/client_server/r0.3.0.html#filtering">Specification.</a>
*/
@Path("/_matrix/client/r0/user")
@Api(value = PATH, description = "Filters can be created on the server and can be passed as as a parameter to APIs which return events. "
+ "These filters alter the data returned from those APIs. Not all APIs accept filters.")
@Path(PATH)
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public interface FilterApi {
/**
* Filter api url.
*/
String PATH = "/_matrix/client/r0/user";
/**
* Uploads a new filter definition to the homeserver. Returns a filter ID that may be used in future requests to restrict which
* events are returned to the client.
* <p/>
* Requires auth: Yes.
* <b>Requires auth</b>: Yes.
*
* @param userId Required. The id of the user uploading the filter. The access token must be authorized to make requests for
* this user id.
......@@ -57,16 +71,25 @@ public interface FilterApi {
* @param securityContext security context.
* @return Status code 200: The filter was created.
*/
@ApiOperation(value = "Ploads a new filter definition to the homeserver.",
notes = "Returns a filter ID that may be used in future requests to restrict which events are returned to the client.",
response = FilterResponse.class)
@ApiResponses( {
@ApiResponse(code = 200, message = "The filter was created.")
})
@POST
@Secured
@Path("/{userId}/filter")
FilterResponse uploadFilter(@PathParam("userId") String userId, FilterData filterData, @Context HttpServletRequest servletRequest,
@Context HttpServletResponse servletResponse, @Context SecurityContext securityContext);
FilterResponse uploadFilter(
@ApiParam(value = "The id of the user uploading the filter. The access token must be authorized to make requests "
+ "for this user id.", required = true) @PathParam("userId") String userId,
@ApiParam("JSON body parameters") FilterData filterData,
@Context HttpServletRequest servletRequest, @Context HttpServletResponse servletResponse, @Context SecurityContext securityContext);
/**
* Download a filter.
* <p/>
* Requires auth: Yes.
* <b>Requires auth</b>: Yes.
*
* @param userId Required. The user ID to download a filter for.
* @param filterId Required. The filter ID to download.
......@@ -76,10 +99,16 @@ public interface FilterApi {
* @return Status code 200: "The filter defintion"
* Status code 404: Unknown filter.
*/
@ApiOperation(value = "Download a filter.", response = FilterData.class)
@ApiResponses( {
@ApiResponse(code = 200, message = "The filter definition."),
@ApiResponse(code = 404, message = "Unknown filter.")
})
@GET
@Secured
@Path("/{userId}/filter/{filterId}")
FilterData getFilter(@PathParam("userId") String userId, @PathParam("filterId") String filterId,
@Context HttpServletRequest servletRequest, @Context HttpServletResponse servletResponse,
@Context SecurityContext securityContext);
FilterData getFilter(
@ApiParam(value = "The user ID to download a filter for.", required = true) @PathParam("userId") String userId,
@ApiParam(value = "The filter ID to download.", required = true) @PathParam("filterId") String filterId,
@Context HttpServletRequest servletRequest, @Context HttpServletResponse servletResponse, @Context SecurityContext securityContext);
}
......@@ -17,23 +17,29 @@
package io.github.ma1uta.matrix.client.model.filter;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
/**
* Filter.
*/
@ApiModel(description = "Filter.")
public class Filter {
/**
* The maximum number of events to return.
*/
@ApiModelProperty("The maximum number of events to return.")
private Long limit;
/**
* A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even
* if it is listed in the 'senders' filter.
*/
@ApiModelProperty(name = "not_senders", value = "A list of sender IDs to exclude. If this list is absent then no senders are "
+ "excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.")
@JsonProperty("not_senders")
private List<String> notSenders;
......@@ -41,18 +47,24 @@ public class Filter {
* A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded
* even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.
*/
@ApiModelProperty(name = "not_types", value = "A list of event types to exclude. If this list is absent then no event types "
+ "are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a "
+ "wildcard to match any sequence of characters.")
@JsonProperty("not_types")
private List<String> notTypes;
/**
* A list of senders IDs to include. If this list is absent then all senders are included.
*/
@ApiModelProperty("A list of senders IDs to include. If this list is absent then all senders are included.")
private List<String> senders;
/**
* A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to
* match any sequence of characters.
*/
@ApiModelProperty("A list of event types to include. If this list is absent then all event types are included. A '*' can "
+ "be used as a wildcard to match any sequence of characters.")
private List<String> types;
public Long getLimit() {
......
......@@ -17,20 +17,23 @@
package io.github.ma1uta.matrix.client.model.filter;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
/**
* JSON body request for filter api (create filter).
*/
@ApiModel(description = "JSON body request for filter api.")
public class FilterData {
/**
* Event formats.
*/
public static final class EventFormat {
public static class EventFormat {
private EventFormat() {
protected EventFormat() {
//singleton
}
......@@ -50,6 +53,10 @@ public class FilterData {
* to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character
* in a field name may be escaped using a '\'. A server may include more fields than were requested.
*/
@ApiModelProperty(name = "event_fields", value = "List of event fields to include. If this list is absent then all fields are "
+ "included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' "
+ "field of the 'content' object. A literal '.' character in a field name may be escaped using a '\'. A server may include "
+ "more fields than were requested.")
@JsonProperty("event_fields")
private List<String> eventFields;
......@@ -57,23 +64,29 @@ public class FilterData {
* The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the
* raw event as receieved over federation. The default is 'client'. One of: ["client", "federation"]
*/
@ApiModelProperty(name = "event_format", value = "The format to use for events. 'client' will return the events in a format "
+ "suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
allowableValues = "['client', 'federation']")
@JsonProperty("event_format")
private String eventFormat;
/**
* The presence updates to include.
*/
@ApiModelProperty("The presence updates to include.")
private Filter presence;
/**
* The user account data that isn't associated with rooms to include.
*/
@ApiModelProperty(name = "account_data", value = "The user account data that isn't associated with rooms to include.")
@JsonProperty("account_data")
private Filter accountData;
/**
* Filters to be applied to room data.
*/
@ApiModelProperty("Filters to be applied to room data.")
private RoomFilter room;
public List<String> getEventFields() {
......
......@@ -17,23 +17,29 @@
package io.github.ma1uta.matrix.client.model.filter;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
/**
* Room event filter.
*/
@ApiModel(description = "Room event filter.")
public class RoomEventFilter {
/**
* The maximum number of events to return.
*/
@ApiModelProperty("The maximum number of events to return.")
private Long limit;
/**
* A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even
* if it is listed in the 'senders' filter.
*/
@ApiModelProperty(name = "not_senders", value = "A list of sender IDs to exclude. If this list is absent then no senders are "
+ "excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.")
@JsonProperty("not_senders")
private List<String> notSenders;
......@@ -41,35 +47,46 @@ public class RoomEventFilter {
* A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even
* if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.
*/
@ApiModelProperty(name = "not_types", value = "A list of event types to exclude. If this list is absent then no event types "
+ "are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a "
+ "wildcard to match any sequence of characters.")
@JsonProperty("not_types")
private List<String> notTypes;
/**
* A list of senders IDs to include. If this list is absent then all senders are included.
*/
@ApiModelProperty("A list of senders IDs to include. If this list is absent then all senders are included.")
private List<String> senders;
/**
* A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to
* match any sequence of characters.
*/
@ApiModelProperty("A list of event types to include. If this list is absent then all event types are included. A '*' can "
+ "be used as a wildcard to match any sequence of characters.")
private List<String> types;
/**
* A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is
* listed in the 'rooms' filter.
*/
@ApiModelProperty(name = "not_rooms", value = "A list of room IDs to exclude. If this list is absent then no rooms are excluded. "
+ "A matching room will be excluded even if it is listed in the 'rooms' filter.")
@JsonProperty("not_rooms")
private List<String> notRooms;
/**
* A list of room IDs to include. If this list is absent then all rooms are included.
*/
@ApiModelProperty("A list of room IDs to include. If this list is absent then all rooms are included.")
private List<String> rooms;
/**
* If true, includes only events with a url key in their content. If false, excludes those events.
*/
@ApiModelProperty(name = "contains_url", value = "If true, includes only events with a url key in their content. If false, "
+ "excludes those events.")
@JsonProperty("contains_url")
private Boolean containsUrl;
......
......@@ -17,51 +17,64 @@
package io.github.ma1uta.matrix.client.model.filter;
import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
/**
* Room filter.
*/
@ApiModel("Room filter.")
public class RoomFilter {
/**
* A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it
* is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data
* is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data.
*/
@ApiModelProperty(name = "not_rooms", value = "A list of room IDs to exclude. If this list is absent then no rooms are excluded. "
+ "A matching room will be excluded even if it is listed in the 'rooms' filter. This filter is applied before the filters in "
+ "ephemeral, state, timeline or account_data.")
@JsonProperty("not_rooms")
private List<String> notRooms;
/**
* A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters
* in ephemeral, state, timeline or account_data
* in ephemeral, state, timeline or account_data.
*/
@ApiModelProperty("A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied "
+ "before the filters in ephemeral, state, timeline or account_data.")
private List<String> rooms;
/**
* The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.
*/
@ApiModelProperty("The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.")
private RoomEventFilter ephemeral;
/**
* Include rooms that the user has left in the sync, default false.
*/
@ApiModelProperty(name = "include_leave", value = "Include rooms that the user has left in the sync, default false.")
@JsonProperty("include_leave")
private Boolean includeLeave;
/**
* The state events to include for rooms.
*/
@ApiModelProperty("The state events to include for rooms.")
private RoomEventFilter state;
/**
* The message and state update events to include for rooms.
*/
@ApiModelProperty("The message and state update events to include for rooms.")
private RoomEventFilter timeline;
/**
* The per user account data to include for rooms.
*/
@ApiModelProperty(name = "account_data", value = "The per user account data to include for rooms.")
@JsonProperty("account_data")
private RoomEventFilter accountData;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment