http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/FunnelResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/FunnelResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/FunnelResource.java index fd97dca..d0ad806 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/FunnelResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/FunnelResource.java @@ -16,6 +16,12 @@ */ package org.apache.nifi.web.api; +import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.net.URI; import java.net.URISyntaxException; import java.util.HashMap; @@ -53,7 +59,6 @@ import org.apache.nifi.web.api.request.ClientIdParameter; import org.apache.nifi.web.api.request.DoubleParameter; import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -61,6 +66,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Funnel. */ +@Api(hidden = true) public class FunnelResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(FunnelResource.class); @@ -95,14 +101,40 @@ public class FunnelResource extends ApplicationResource { /** * Retrieves all the of funnels in this NiFi. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @return A funnelsEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(FunnelsEntity.class) - public Response getFunnels(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets all funnels", + response = FunnelsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getFunnels( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -129,8 +161,11 @@ public class FunnelResource extends ApplicationResource { * Creates a new funnel. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param x The x coordinate for this funnels position. * @param y The y coordinate for this funnels position. * @return A funnelEntity. @@ -138,8 +173,8 @@ public class FunnelResource extends ApplicationResource { @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FunnelEntity.class) public Response createFunnel( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -181,11 +216,30 @@ public class FunnelResource extends ApplicationResource { @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FunnelEntity.class) + @ApiOperation( + value = "Creates a funnel", + response = FunnelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response createFunnel( @Context HttpServletRequest httpServletRequest, - FunnelEntity funnelEntity) { + @ApiParam( + value = "The funnel configuration details.", + required = true + ) FunnelEntity funnelEntity) { if (funnelEntity == null || funnelEntity.getFunnel() == null) { throw new IllegalArgumentException("Funnel details must be specified."); @@ -254,16 +308,46 @@ public class FunnelResource extends ApplicationResource { /** * Retrieves the specified funnel. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param id The id of the funnel to retrieve * @return A funnelEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(FunnelEntity.class) - public Response getFunnel(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a funnel", + response = FunnelEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getFunnel( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The funnel id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -289,8 +373,11 @@ public class FunnelResource extends ApplicationResource { * Updates the specified funnel. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param id The id of the funnel to update. * @param parentGroupId The id of the process group to move this funnel to. * @param x The x coordinate for this funnels position. @@ -302,7 +389,6 @@ public class FunnelResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FunnelEntity.class) public Response updateFunnel( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -350,11 +436,33 @@ public class FunnelResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FunnelEntity.class) + @ApiOperation( + value = "Updates a funnel", + response = FunnelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateFunnel( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The funnel id.", + required = true + ) @PathParam("id") String id, - FunnelEntity funnelEntity) { + @ApiParam( + value = "The funnel configuration details.", + required = true + ) FunnelEntity funnelEntity) { if (funnelEntity == null || funnelEntity.getFunnel() == null) { throw new IllegalArgumentException("Funnel details must be specified."); @@ -413,20 +521,51 @@ public class FunnelResource extends ApplicationResource { * Removes the specified funnel. * * @param httpServletRequest request - * @param version The revision is used to verify the client is working with the latest version of the flow. - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param version The revision is used to verify the client is working with + * the latest version of the flow. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param id The id of the funnel to remove. * @return A entity containing the client id and an updated revision. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FunnelEntity.class) + @ApiOperation( + value = "Deletes a funnel", + response = FunnelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response removeFunnel( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @QueryParam(VERSION) LongParameter version, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The funnel id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager
http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/HistoryResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/HistoryResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/HistoryResource.java index 749863c..7462ff8 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/HistoryResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/HistoryResource.java @@ -16,6 +16,13 @@ */ package org.apache.nifi.web.api; +import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; +import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; import javax.ws.rs.GET; @@ -38,12 +45,12 @@ import org.apache.nifi.web.api.dto.action.ActionDTO; import org.apache.nifi.web.api.dto.action.HistoryDTO; import org.apache.nifi.web.api.dto.action.HistoryQueryDTO; import org.apache.nifi.web.api.entity.ComponentHistoryEntity; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for querying the history of this Controller. */ +@Api(hidden = true) public class HistoryResource extends ApplicationResource { private NiFiServiceFacade serviceFacade; @@ -51,28 +58,99 @@ public class HistoryResource extends ApplicationResource { /** * Queries the history of this Controller. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. - * @param offset The offset into the data. This parameter is required and is used in conjunction with count. - * @param count The number of rows that should be returned. This parameter is required and is used in conjunction with page. - * @param sortColumn The column to sort on. This parameter is optional. If not specified the results will be returned with the most recent first. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. + * @param offset The offset into the data. This parameter is required and is + * used in conjunction with count. + * @param count The number of rows that should be returned. This parameter + * is required and is used in conjunction with page. + * @param sortColumn The column to sort on. This parameter is optional. If + * not specified the results will be returned with the most recent first. * @param sortOrder The sort order. - * @param startDate The start date/time for the query. The start date/time must be formatted as 'MM/dd/yyyy HH:mm:ss'. This parameter is optional and must be specified in the timezone of the - * server. The server's timezone can be determined by inspecting the result of a status or history request. - * @param endDate The end date/time for the query. The end date/time must be formatted as 'MM/dd/yyyy HH:mm:ss'. This parameter is optional and must be specified in the timezone of the server. The - * server's timezone can be determined by inspecting the result of a status or history request. - * @param userName The user name of the user who's actions are being queried. This parameter is optional. - * @param sourceId The id of the source being queried (usually a processor id). This parameter is optional. + * @param startDate The start date/time for the query. The start date/time + * must be formatted as 'MM/dd/yyyy HH:mm:ss'. This parameter is optional + * and must be specified in the timezone of the server. The server's + * timezone can be determined by inspecting the result of a status or + * history request. + * @param endDate The end date/time for the query. The end date/time must be + * formatted as 'MM/dd/yyyy HH:mm:ss'. This parameter is optional and must + * be specified in the timezone of the server. The server's timezone can be + * determined by inspecting the result of a status or history request. + * @param userName The user name of the user who's actions are being + * queried. This parameter is optional. + * @param sourceId The id of the source being queried (usually a processor + * id). This parameter is optional. * @return A historyEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(HistoryEntity.class) - public Response queryHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, - @QueryParam("offset") IntegerParameter offset, @QueryParam("count") IntegerParameter count, - @QueryParam("sortColumn") String sortColumn, @QueryParam("sortOrder") String sortOrder, - @QueryParam("startDate") DateTimeParameter startDate, @QueryParam("endDate") DateTimeParameter endDate, - @QueryParam("userName") String userName, @QueryParam("sourceId") String sourceId) { + @ApiOperation( + value = "Gets configuration history", + response = HistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response queryHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The offset into the result set.", + required = true + ) + @QueryParam("offset") IntegerParameter offset, + @ApiParam( + value = "The number of actions to return.", + required = true + ) + @QueryParam("count") IntegerParameter count, + @ApiParam( + value = "The field to sort on.", + required = false + ) + @QueryParam("sortColumn") String sortColumn, + @ApiParam( + value = "The direction to sort.", + required = false + ) + @QueryParam("sortOrder") String sortOrder, + @ApiParam( + value = "Include actions after this date.", + required = false + ) + @QueryParam("startDate") DateTimeParameter startDate, + @ApiParam( + value = "Include actions before this date.", + required = false + ) + @QueryParam("endDate") DateTimeParameter endDate, + @ApiParam( + value = "Include actions performed by this user.", + required = false + ) + @QueryParam("userName") String userName, + @ApiParam( + value = "Include actions on this component.", + required = false + ) + @QueryParam("sourceId") String sourceId) { // ensure the page is specified if (offset == null) { @@ -148,16 +226,45 @@ public class HistoryResource extends ApplicationResource { /** * Gets the action for the corresponding id. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param id The id of the action to get. * @return An actionEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @Path("{id}") - @TypeHint(ActionEntity.class) - public Response getAction(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiOperation( + value = "Gets an action", + response = ActionEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getAction( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The action id.", + required = true + ) @PathParam("id") IntegerParameter id) { // ensure the id was specified @@ -184,16 +291,42 @@ public class HistoryResource extends ApplicationResource { /** * Deletes flow history from the specified end date. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param endDate The end date for the purge action. * @return A historyEntity */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_ADMIN')") - @TypeHint(HistoryEntity.class) + @ApiOperation( + value = "Purges history", + response = HistoryEntity.class, + authorizations = { + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response deleteHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "Purge actions before this date/time.", + required = true + ) @QueryParam("endDate") DateTimeParameter endDate) { // ensure the end date is specified @@ -219,17 +352,45 @@ public class HistoryResource extends ApplicationResource { /** * Gets the actions for the specified processor. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param processorId The id of the processor. * @return An processorHistoryEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @Path("/processors/{processorId}") - @TypeHint(ComponentHistoryEntity.class) + @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") + @ApiOperation( + value = "Gets configuration history for a processor", + response = ComponentHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getProcessorHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The processor id.", + required = true + ) @PathParam("processorId") final String processorId) { // create the revision @@ -248,17 +409,45 @@ public class HistoryResource extends ApplicationResource { /** * Gets the actions for the specified controller service. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param controllerServiceId The id of the controller service. * @return An componentHistoryEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @Path("/controller-services/{controllerServiceId}") - @TypeHint(ComponentHistoryEntity.class) + @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") + @ApiOperation( + value = "Gets configuration history for a controller service", + response = ComponentHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getControllerServiceHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The controller service id.", + required = true + ) @PathParam("controllerServiceId") final String controllerServiceId) { // create the revision @@ -277,17 +466,45 @@ public class HistoryResource extends ApplicationResource { /** * Gets the actions for the specified reporting task. * - * @param clientId Optional client id. If the client id is not specified, a new one will be generated. This value (whether specified or generated) is included in the response. + * @param clientId Optional client id. If the client id is not specified, a + * new one will be generated. This value (whether specified or generated) is + * included in the response. * @param reportingTaskId The id of the reporting task. * @return An componentHistoryEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") @Path("/reporting-tasks/{reportingTaskId}") - @TypeHint(ComponentHistoryEntity.class) + @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") + @ApiOperation( + value = "Gets configuration history for a reporting task", + response = ComponentHistoryEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response getReportingTaskHistory( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The reporting task id.", + required = true + ) @PathParam("reportingTaskId") final String reportingTaskId) { // create the revision http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/InputPortResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/InputPortResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/InputPortResource.java index 4e446fb..b4c4607 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/InputPortResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/InputPortResource.java @@ -16,6 +16,12 @@ */ package org.apache.nifi.web.api; +import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.net.URI; import java.net.URISyntaxException; import java.util.HashMap; @@ -55,7 +61,6 @@ import org.apache.nifi.web.api.request.DoubleParameter; import org.apache.nifi.web.api.request.IntegerParameter; import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -63,6 +68,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing an Input Port. */ +@Api(hidden = true) public class InputPortResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(InputPortResource.class); @@ -101,10 +107,34 @@ public class InputPortResource extends ApplicationResource { * @return A inputPortsEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(InputPortsEntity.class) - public Response getInputPorts(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets all input ports", + response = InputPortsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getInputPorts( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -141,8 +171,8 @@ public class InputPortResource extends ApplicationResource { @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(InputPortEntity.class) public Response createInputPort( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -187,11 +217,30 @@ public class InputPortResource extends ApplicationResource { @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(InputPortEntity.class) + @ApiOperation( + value = "Creates an input port", + response = InputPortEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response createInputPort( @Context HttpServletRequest httpServletRequest, - InputPortEntity portEntity) { + @ApiParam( + value = "The input port configuration details.", + required = true + ) InputPortEntity portEntity) { if (portEntity == null || portEntity.getInputPort() == null) { throw new IllegalArgumentException("Port details must be specified."); @@ -266,11 +315,39 @@ public class InputPortResource extends ApplicationResource { * @return A inputPortEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(InputPortEntity.class) - public Response getInputPort(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets an input port", + response = InputPortEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getInputPort( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The input port id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -315,7 +392,6 @@ public class InputPortResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(InputPortEntity.class) public Response updateInputPort( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -386,11 +462,33 @@ public class InputPortResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(InputPortEntity.class) + @ApiOperation( + value = "Updates an input port", + response = InputPortEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateInputPort( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The input port id.", + required = true + ) @PathParam("id") String id, - InputPortEntity portEntity) { + @ApiParam( + value = "The input port configuration details.", + required = true + ) InputPortEntity portEntity) { if (portEntity == null || portEntity.getInputPort() == null) { throw new IllegalArgumentException("Input port details must be specified."); @@ -456,14 +554,42 @@ public class InputPortResource extends ApplicationResource { * @return A inputPortEntity. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(InputPortEntity.class) + @ApiOperation( + value = "Deletes an input port", + response = InputPortEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response removeInputPort( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @QueryParam(VERSION) LongParameter version, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The input port id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/LabelResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/LabelResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/LabelResource.java index 6b12d0e..b6edb71 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/LabelResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/LabelResource.java @@ -16,6 +16,12 @@ */ package org.apache.nifi.web.api; +import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import java.net.URI; import java.net.URISyntaxException; import java.util.HashMap; @@ -55,7 +61,6 @@ import org.apache.nifi.web.api.request.ClientIdParameter; import org.apache.nifi.web.api.request.DoubleParameter; import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -63,6 +68,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Label. */ +@Api(hidden = true) public class LabelResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(LabelResource.class); @@ -101,10 +107,34 @@ public class LabelResource extends ApplicationResource { * @return A labelsEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(LabelsEntity.class) - public Response getLabels(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets all labels", + response = LabelsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getLabels( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -143,8 +173,8 @@ public class LabelResource extends ApplicationResource { @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(LabelEntity.class) public Response createLabel( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -197,11 +227,30 @@ public class LabelResource extends ApplicationResource { @POST @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(LabelEntity.class) + @ApiOperation( + value = "Creates a label", + response = LabelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response createLabel( @Context HttpServletRequest httpServletRequest, - LabelEntity labelEntity) { + @ApiParam( + value = "The label configuration details.", + required = true + ) LabelEntity labelEntity) { if (labelEntity == null || labelEntity.getLabel() == null) { throw new IllegalArgumentException("Label details must be specified."); @@ -275,11 +324,39 @@ public class LabelResource extends ApplicationResource { * @return A labelEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(LabelEntity.class) - public Response getLabel(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a label", + response = LabelEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getLabel( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The label id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -326,7 +403,6 @@ public class LabelResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(LabelEntity.class) public Response updateLabel( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -404,11 +480,33 @@ public class LabelResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(LabelEntity.class) + @ApiOperation( + value = "Updates a label", + response = LabelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response updateLabel( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The label id.", + required = true + ) @PathParam("id") String id, - LabelEntity labelEntity) { + @ApiParam( + value = "The label configuraiton details.", + required = true + ) LabelEntity labelEntity) { if (labelEntity == null || labelEntity.getLabel() == null) { throw new IllegalArgumentException("Label details must be specified."); @@ -473,14 +571,42 @@ public class LabelResource extends ApplicationResource { * @return A entity containing the client id and an updated revision. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(LabelEntity.class) + @ApiOperation( + value = "Deletes a label", + response = LabelEntity.class, + authorizations = { + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response removeLabel( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @QueryParam(VERSION) LongParameter version, + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The label id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/997ed946/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/NodeResource.java ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/NodeResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/NodeResource.java index bb0eba9..c88cc68 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/NodeResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/NodeResource.java @@ -16,6 +16,12 @@ */ package org.apache.nifi.web.api; +import com.wordnik.swagger.annotations.Api; +import com.wordnik.swagger.annotations.ApiOperation; +import com.wordnik.swagger.annotations.ApiParam; +import com.wordnik.swagger.annotations.ApiResponse; +import com.wordnik.swagger.annotations.ApiResponses; +import com.wordnik.swagger.annotations.Authorization; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.DefaultValue; @@ -40,12 +46,12 @@ import org.apache.nifi.web.api.dto.RevisionDTO; import org.apache.nifi.web.api.dto.status.NodeStatusDTO; import org.apache.nifi.web.api.entity.ProcessGroupStatusEntity; import org.apache.nifi.web.api.entity.SystemDiagnosticsEntity; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a cluster connection. */ +@Api(hidden = true) public class NodeResource extends ApplicationResource { private NiFiServiceFacade serviceFacade; @@ -59,11 +65,39 @@ public class NodeResource extends ApplicationResource { * @return A nodeEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(NodeEntity.class) - public Response getNode(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a node in the cluster", + response = NodeEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getNode( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The node id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { @@ -95,11 +129,39 @@ public class NodeResource extends ApplicationResource { * @return A processGroupStatusEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessGroupStatusEntity.class) - public Response getNodeStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets process group status for a node in the cluster", + response = ProcessGroupStatusEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getNodeStatus( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The node id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { // get the node statistics @@ -129,11 +191,39 @@ public class NodeResource extends ApplicationResource { * @return A systemDiagnosticsEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}/system-diagnostics") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(SystemDiagnosticsEntity.class) - public Response getNodeSystemDiagnostics(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets system diagnostics for a node in the cluester", + response = SystemDiagnosticsEntity.class, + authorizations = { + @Authorization(value = "Read Only", type = "ROLE_MONITOR"), + @Authorization(value = "Data Flow Manager", type = "ROLE_DFM"), + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response getNodeSystemDiagnostics( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) + @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The node id.", + required = true + ) + @PathParam("id") String id) { if (properties.isClusterManager()) { // get the node statistics @@ -169,7 +259,6 @@ public class NodeResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_ADMIN')") - @TypeHint(NodeEntity.class) public Response updateNode(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id, @FormParam("status") String status, @@ -206,8 +295,33 @@ public class NodeResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_ADMIN')") - @TypeHint(NodeEntity.class) - public Response updateNode(@PathParam("id") String id, NodeEntity nodeEntity) { + @ApiOperation( + value = "Updates a node in the cluster", + response = NodeEntity.class, + authorizations = { + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) + public Response updateNode( + @ApiParam( + value = "The node id.", + required = true + ) + @PathParam("id") String id, + @ApiParam( + value = "The node configuration. The only configuration that will be honored at this endpoint is the status or primary flag.", + required = true + ) + NodeEntity nodeEntity) { if (properties.isClusterManager()) { @@ -253,11 +367,36 @@ public class NodeResource extends ApplicationResource { * @return A nodeEntity */ @DELETE + @Consumes(MediaType.WILDCARD) + @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_ADMIN')") - @TypeHint(NodeEntity.class) + @ApiOperation( + value = "Removes a node from the cluster", + response = NodeEntity.class, + authorizations = { + @Authorization(value = "Administrator", type = "ROLE_ADMIN") + } + ) + @ApiResponses( + value = { + @ApiResponse(code = 400, message = "NiFi was unable to complete the request because it was invalid. The request should not be retried without modification."), + @ApiResponse(code = 401, message = "Client could not be authenticated."), + @ApiResponse(code = 403, message = "Client is not authorized to make this request."), + @ApiResponse(code = 404, message = "The specified resource could not be found."), + @ApiResponse(code = 409, message = "The request was valid but NiFi was not in the appropriate state to process it. Retrying the same request later may be successful.") + } + ) public Response deleteNode( + @ApiParam( + value = "If the client id is not specified, new one will be generated. This value (whether specified or generated) is included in the response.", + required = false + ) @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The node id.", + required = true + ) @PathParam("id") String id) { if (properties.isClusterManager()) {
