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/OutputPortResource.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/OutputPortResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/OutputPortResource.java index a600d35..127ac43 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/OutputPortResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/OutputPortResource.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 Output Port. */ +@Api(hidden = true) public class OutputPortResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(OutputPortResource.class); @@ -101,10 +107,34 @@ public class OutputPortResource extends ApplicationResource { * @return A outputPortsEntity. */ @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(OutputPortsEntity.class) - public Response getOutputPorts(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets all output ports", + response = OutputPortsEntity.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 getOutputPorts( + @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 OutputPortResource 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(OutputPortEntity.class) public Response createOutputPort( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -187,11 +217,30 @@ public class OutputPortResource 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(OutputPortEntity.class) + @ApiOperation( + value = "Creates an output port", + response = OutputPortEntity.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 createOutputPort( @Context HttpServletRequest httpServletRequest, - OutputPortEntity portEntity) { + @ApiParam( + value = "The output port configuration.", + required = true + ) OutputPortEntity portEntity) { if (portEntity == null || portEntity.getOutputPort() == null) { throw new IllegalArgumentException("Port details must be specified."); @@ -266,11 +315,39 @@ public class OutputPortResource extends ApplicationResource { * @return A outputPortEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(OutputPortEntity.class) - public Response getOutputPort(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets an output port", + response = OutputPortEntity.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 getOutputPort( + @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 output port id.", + required = true + ) + @PathParam("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -315,7 +392,6 @@ public class OutputPortResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(OutputPortEntity.class) public Response updateOutputPort( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -387,11 +463,33 @@ public class OutputPortResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(OutputPortEntity.class) + @ApiOperation( + value = "Updates an output port", + response = OutputPortEntity.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 updateOutputPort( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The output port id.", + required = true + ) @PathParam("id") String id, - OutputPortEntity portEntity) { + @ApiParam( + value = "The output port configuration details.", + required = true + ) OutputPortEntity portEntity) { if (portEntity == null || portEntity.getOutputPort() == null) { throw new IllegalArgumentException("Output port details must be specified."); @@ -457,14 +555,42 @@ public class OutputPortResource extends ApplicationResource { * @return A outputPortEntity. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(OutputPortEntity.class) + @ApiOperation( + value = "Deletes an output port", + response = OutputPortEntity.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 removeOutputPort( @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 output 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/ProcessGroupResource.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/ProcessGroupResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessGroupResource.java index 2b3657e..3e82bad 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessGroupResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessGroupResource.java @@ -17,6 +17,12 @@ package org.apache.nifi.web.api; import com.sun.jersey.api.core.ResourceContext; +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; @@ -62,12 +68,12 @@ 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.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Group. */ +@Api(hidden = true) public class ProcessGroupResource extends ApplicationResource { private static final String VERBOSE = "false"; @@ -87,6 +93,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the processor resource within the specified group */ @Path("processors") + @ApiOperation( + value = "Gets the processor resource", + response = ProcessorResource.class + ) public ProcessorResource getProcessorResource() { ProcessorResource processorResource = resourceContext.getResource(ProcessorResource.class); processorResource.setGroupId(groupId); @@ -99,6 +109,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the connection sub-resource within the specified group */ @Path("connections") + @ApiOperation( + value = "Gets the connection resource", + response = ConnectionResource.class + ) public ConnectionResource getConnectionResource() { ConnectionResource connectionResource = resourceContext.getResource(ConnectionResource.class); connectionResource.setGroupId(groupId); @@ -111,6 +125,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the input ports sub-resource within the specified group */ @Path("input-ports") + @ApiOperation( + value = "Gets the input port resource", + response = InputPortResource.class + ) public InputPortResource getInputPortResource() { InputPortResource inputPortResource = resourceContext.getResource(InputPortResource.class); inputPortResource.setGroupId(groupId); @@ -123,6 +141,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the output ports sub-resource within the specified group */ @Path("output-ports") + @ApiOperation( + value = "Gets the output port resource", + response = OutputPortResource.class + ) public OutputPortResource getOutputPortResource() { OutputPortResource outputPortResource = resourceContext.getResource(OutputPortResource.class); outputPortResource.setGroupId(groupId); @@ -135,6 +157,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the label sub-resource within the specified group */ @Path("labels") + @ApiOperation( + value = "Gets the label resource", + response = LabelResource.class + ) public LabelResource getLabelResource() { LabelResource labelResource = resourceContext.getResource(LabelResource.class); labelResource.setGroupId(groupId); @@ -147,6 +173,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the funnel sub-resource within the specified group */ @Path("funnels") + @ApiOperation( + value = "Gets the funnel resource", + response = FunnelResource.class + ) public FunnelResource getFunnelResource() { FunnelResource funnelResource = resourceContext.getResource(FunnelResource.class); funnelResource.setGroupId(groupId); @@ -159,6 +189,10 @@ public class ProcessGroupResource extends ApplicationResource { * @return the remote process group sub-resource within the specified group */ @Path("remote-process-groups") + @ApiOperation( + value = "Gets the remote process group resource", + response = RemoteProcessGroupResource.class + ) public RemoteProcessGroupResource getRemoteProcessGroupResource() { RemoteProcessGroupResource remoteProcessGroupResource = resourceContext.getResource(RemoteProcessGroupResource.class); remoteProcessGroupResource.setGroupId(groupId); @@ -242,12 +276,47 @@ public class ProcessGroupResource extends ApplicationResource { * @return A processGroupEntity. */ @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(ProcessGroupEntity.class) + @ApiOperation( + value = "Gets a process group", + notes = "Gets a process group and includes all components contained in this group. The verbose and recursive flags can be used to adjust " + + "the default behavior. This endpoint is starting point for obtaining the current flow and consequently includes the current " + + "flow revision.", + response = ProcessGroupEntity.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 getProcessGroup( + @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 = "Whether the response should contain all encapsulated components or just the immediate children.", + required = false, + allowableValues = "true, false" + ) @QueryParam("recursive") @DefaultValue(RECURSIVE) Boolean recursive, + @ApiParam( + value = "Whether to include any encapulated components or just details about the process group.", + required = false + ) @QueryParam("verbose") @DefaultValue(VERBOSE) Boolean verbose) { // replicate if cluster manager @@ -296,13 +365,48 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/snippet-instance") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FlowSnippetEntity.class) + @ApiOperation( + value = "Copies a snippet", + response = FlowSnippetEntity.class, + authorizations = { + @Authorization(value = "ROLE_DFM", 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 copySnippet( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @FormParam(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 + ) @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The snippet id.", + required = true + ) @FormParam("snippetId") String snippetId, + @ApiParam( + value = "The x coordinate of the origin of the bounding box where the new components will be placed.", + required = true + ) @FormParam("originX") DoubleParameter originX, + @ApiParam( + value = "The y coordinate of the origin of the bounding box where the new components will be placed.", + required = true + ) @FormParam("originY") DoubleParameter originY) { // ensure the position has been specified @@ -372,13 +476,48 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/template-instance") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(FlowSnippetEntity.class) + @ApiOperation( + value = "Instantiates a template", + response = FlowSnippetEntity.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 instantiateTemplate( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = false + ) @FormParam(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 + ) @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the template", + required = false + ) @FormParam("templateId") String templateId, + @ApiParam( + value = "The x coordinate of the origin of the bounding box where the new components will be placed.", + required = true + ) @FormParam("originX") DoubleParameter originX, + @ApiParam( + value = "The y coordinate of the origin of the bounding box where the new components will be placed.", + required = true + ) @FormParam("originY") DoubleParameter originY) { // ensure the position has been specified @@ -441,8 +580,8 @@ public class ProcessGroupResource extends ApplicationResource { @PUT @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) public Response updateProcessGroup( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -481,10 +620,33 @@ public class ProcessGroupResource extends ApplicationResource { @PUT @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(ProcessGroupEntity.class) + @ApiOperation( + value = "Updates a process group", + response = ProcessGroupEntity.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 updateProcessGroup( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The process group to update. The only action that is supported at this endpoint is to set the running flag in order " + + "to start or stop all descendent schedulable components. This defines the schema of the expected input.", + required = true + ) ProcessGroupEntity processGroupEntity) { if (processGroupEntity == null || processGroupEntity.getProcessGroup() == null) { @@ -549,14 +711,48 @@ public class ProcessGroupResource extends ApplicationResource { * @return A processGroupEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessGroupEntity.class) + @ApiOperation( + value = "Gets a process group", + response = ProcessGroupEntity.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 getProcessGroup( + @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 process group id.", + required = false + ) @PathParam("id") String processGroupReferenceId, + @ApiParam( + value = "Whether the response should contain all encapsulated components or just the immediate children.", + required = false + ) @QueryParam("recursive") @DefaultValue(RECURSIVE) Boolean recursive, + @ApiParam( + value = "Whether to include any encapulated components or just details about the process group.", + required = false + ) @QueryParam("verbose") @DefaultValue(VERBOSE) Boolean verbose) { // replicate if cluster manager @@ -597,12 +793,38 @@ public class ProcessGroupResource extends ApplicationResource { * @return A controllerEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessGroupsEntity.class) + @ApiOperation( + value = "Gets all process groups", + response = ProcessGroupsEntity.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 getProcessGroupReferences( + @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 = "Whether to include any encapulated components or just details about the process group.", + required = false + ) @QueryParam("verbose") @DefaultValue(VERBOSE) Boolean verbose) { // replicate if cluster manager @@ -648,7 +870,6 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) public Response createProcessGroupReference( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -694,9 +915,28 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) + @ApiOperation( + value = "Creates a process group", + response = ProcessGroupEntity.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 createProcessGroupReference( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The process group configuration details.", + required = true + ) ProcessGroupEntity processGroupEntity) { if (processGroupEntity == null || processGroupEntity.getProcessGroup() == null) { @@ -782,7 +1022,6 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) public Response updateProcessGroupReference( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -836,10 +1075,33 @@ public class ProcessGroupResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) + @ApiOperation( + value = "Updates a process group", + response = ProcessGroupEntity.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 updateProcessGroupReference( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The process group id.", + required = true + ) @PathParam("id") String id, + @ApiParam( + value = "The process group configuration details.", + required = true + ) ProcessGroupEntity processGroupEntity) { if (processGroupEntity == null || processGroupEntity.getProcessGroup() == null) { @@ -904,14 +1166,42 @@ public class ProcessGroupResource extends ApplicationResource { * @return A processGroupEntity. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/process-group-references/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) + @ApiOperation( + value = "Deletes a process group", + response = ProcessGroupEntity.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 removeProcessGroupReference( @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 process group id.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -956,10 +1246,31 @@ public class ProcessGroupResource extends ApplicationResource { * @return A processGroupStatusEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN', 'ROLE_NIFI')") - @TypeHint(ProcessGroupStatusEntity.class) + @ApiOperation( + value = "Gets the status for a process group", + notes = "The status for a process group includes status for all descendent components. When invoked on the root group with " + + "recursive set to true, it will return the current status of every component in the flow.", + 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"), + @Authorization(value = "NiFi", type="ROLE_NIFI") + } + ) + @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 getProcessGroupStatus( @QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @QueryParam("recursive") @DefaultValue(RECURSIVE) Boolean recursive) { @@ -999,10 +1310,28 @@ public class ProcessGroupResource extends ApplicationResource { * @return A processorEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(StatusHistoryEntity.class) + @ApiOperation( + value = "Gets status history for a remote process group", + response = StatusHistoryEntity.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 getProcessGroupStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { // 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/ProcessorResource.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/ProcessorResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessorResource.java index 16c7e19..f972c07 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessorResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProcessorResource.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.Arrays; @@ -75,7 +81,6 @@ import org.apache.nifi.ui.extension.UiExtensionMapping; import org.apache.nifi.web.UiExtensionType; import org.apache.nifi.web.api.dto.PropertyDescriptorDTO; import org.apache.nifi.web.api.entity.PropertyDescriptorEntity; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -83,6 +88,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Processor. */ +@Api(hidden = true) public class ProcessorResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(ProcessorResource.class); @@ -148,9 +154,28 @@ public class ProcessorResource extends ApplicationResource { * @return A processorsEntity. */ @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(ProcessorsEntity.class) + @ApiOperation( + value = "Gets all processors", + response = ProcessorsEntity.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 getProcessors(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { // replicate if cluster manager @@ -189,8 +214,8 @@ public class ProcessorResource 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(ProcessorEntity.class) public Response createProcessor( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -236,10 +261,30 @@ public class ProcessorResource 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(ProcessorEntity.class) + @ApiOperation( + value = "Creates a new processor", + response = ProcessorEntity.class, + authorizations = { + @Authorization(value = "ROLE_DFM", 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 createProcessor( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The processor configuration details.", + required = true + ) ProcessorEntity processorEntity) { if (processorEntity == null || processorEntity.getProcessor() == null) { @@ -320,11 +365,39 @@ public class ProcessorResource extends ApplicationResource { * @return A processorEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessorEntity.class) - public Response getProcessor(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a processor", + response = ProcessorEntity.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 getProcessor( + @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("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -355,11 +428,39 @@ public class ProcessorResource extends ApplicationResource { * @return A statusHistoryEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}/status/history") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(StatusHistoryEntity.class) - public Response getProcessorStatusHistory(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + @ApiOperation( + value = "Gets status history for a processor", + response = StatusHistoryEntity.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 getProcessorStatusHistory( + @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("id") String id) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -391,13 +492,44 @@ public class ProcessorResource extends ApplicationResource { * @return a propertyDescriptorEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}/descriptors") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(PropertyDescriptorEntity.class) + @ApiOperation( + value = "Gets the descriptor for a processor property", + response = PropertyDescriptorEntity.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 getPropertyDescriptor( + @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, - @PathParam("id") String id, @QueryParam("propertyName") String propertyName) { + @ApiParam( + value = "The processor id.", + required = true + ) + @PathParam("id") String id, + @ApiParam( + value = "The property name.", + required = true + ) + @QueryParam("propertyName") String propertyName) { // ensure the property name is specified if (propertyName == null) { @@ -466,7 +598,6 @@ public class ProcessorResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessorEntity.class) public Response updateProcessor( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -592,10 +723,33 @@ public class ProcessorResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessorEntity.class) + @ApiOperation( + value = "Updates a processor", + response = ProcessorEntity.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 updateProcessor( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The processor id.", + required = true + ) @PathParam("id") String id, + @ApiParam( + value = "The processor configuration details.", + required = true + ) ProcessorEntity processorEntity) { if (processorEntity == null || processorEntity.getProcessor() == null) { @@ -671,14 +825,42 @@ public class ProcessorResource extends ApplicationResource { * @return A processorEntity. */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessorEntity.class) + @ApiOperation( + value = "Deletes a processor", + response = ProcessorEntity.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 deleteProcessor( @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 processor 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/ProvenanceResource.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/ProvenanceResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java index 4bfe3a0..afa404d 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ProvenanceResource.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.io.IOException; import java.io.InputStream; import java.io.OutputStream; @@ -77,7 +83,6 @@ import org.apache.nifi.web.api.request.LongParameter; import org.apache.nifi.web.DownloadableContent; 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; @@ -85,6 +90,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for querying data provenance. */ +@Api(hidden = true) public class ProvenanceResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(ProvenanceResource.class); @@ -117,11 +123,32 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceOptionsEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/search-options") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(ProvenanceOptionsEntity.class) - public Response getSearchOptions(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the searchable attributes for provenance events", + response = ProvenanceOptionsEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getSearchOptions( + @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()) { return clusterManager.applyRequest(HttpMethod.GET, getAbsolutePath(), getRequestParameters(true), getHeaders()).getResponse(); @@ -153,14 +180,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEventEntity */ @POST + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) - @PreAuthorize("hasRole('ROLE_PROVENANCE') and hasRole('ROLE_DFM')") @Path("/replays") - @TypeHint(ProvenanceEventEntity.class) + @PreAuthorize("hasRole('ROLE_PROVENANCE') and hasRole('ROLE_DFM')") + @ApiOperation( + value = "Replays content from a provenance event", + response = ProvenanceEventEntity.class, + authorizations = { + @Authorization(value = "Provenance and Data Flow Manager", type = "ROLE_PROVENANCE and 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 submitReplay( @Context HttpServletRequest httpServletRequest, + @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 + ) @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, + @ApiParam( + value = "The id of the node where the content exists if clustered.", + required = false + ) @FormParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @FormParam("eventId") LongParameter eventId) { // ensure the event id is specified @@ -220,12 +275,40 @@ public class ProvenanceResource extends ApplicationResource { * @return The content stream */ @GET + @Consumes(MediaType.WILDCARD) @Produces(MediaType.APPLICATION_OCTET_STREAM) @Path("/events/{id}/content/input") @PreAuthorize("hasRole('ROLE_PROVENANCE')") + @ApiOperation( + value = "Gets the input content for a provenance event", + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getInputContent( + @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 id of the node where the content exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure proper input @@ -291,12 +374,40 @@ public class ProvenanceResource extends ApplicationResource { * @return The content stream */ @GET + @Consumes(MediaType.WILDCARD) @Produces(MediaType.APPLICATION_OCTET_STREAM) @Path("/events/{id}/content/output") @PreAuthorize("hasRole('ROLE_PROVENANCE')") + @ApiOperation( + value = "Gets the output content for a provenance event", + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getOutputContent( + @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 id of the node where the content exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenance event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure proper input @@ -374,9 +485,10 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) + @Path("") // necessary due to bug in swagger @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(ProvenanceEntity.class) public Response submitProvenanceRequest( @Context HttpServletRequest httpServletRequest, @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @@ -456,11 +568,33 @@ public class ProvenanceResource 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_PROVENANCE')") - @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Submits a provenance query", + notes = "Provenance queries may be long running so this endpoint submits a request. The response will include the " + + "current state of the query. If the request is not completed the URI in the response can be used at a " + + "later time to get the updated state of the query. Once the query has completed the provenance request " + + "should be deleted by the client who originally submitted it.", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 submitProvenanceRequest( @Context HttpServletRequest httpServletRequest, - ProvenanceEntity provenanceEntity) { + @ApiParam( + value = "The provenance query details.", + required = true + ) ProvenanceEntity provenanceEntity) { // check the request if (provenanceEntity == null) { @@ -548,13 +682,41 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Gets a provenance query", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getProvenance( + @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 id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the provenance query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -606,14 +768,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEntity */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(ProvenanceEntity.class) + @ApiOperation( + value = "Deletes a provenance query", + response = ProvenanceEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 deleteProvenance( @Context HttpServletRequest httpServletRequest, + @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 id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the provenance query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -667,13 +857,41 @@ public class ProvenanceResource extends ApplicationResource { * @return A provenanceEventEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/events/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(ProvenanceEventEntity.class) + @ApiOperation( + value = "Gets a provenance event", + response = ProvenanceEventEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getProvenanceEvent( + @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 id of the node where this event exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The provenence event id.", + required = true + ) @PathParam("id") LongParameter id) { // ensure the id is specified @@ -738,10 +956,10 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @POST + @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(LineageEntity.class) public Response submitLineageRequest( @Context HttpServletRequest httpServletRequest, @FormParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @@ -803,9 +1021,32 @@ public class ProvenanceResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Submits a lineage query", + notes = "Lineage queries may be long running so this endpoint submits a request. The response will include the " + + "current state of the query. If the request is not completed the URI in the response can be used at a " + + "later time to get the updated state of the query. Once the query has completed the lineage request " + + "should be deleted by the client who originally submitted it.", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 submitLineageRequest( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The lineage query details.", + required = true + ) final LineageEntity lineageEntity) { if (lineageEntity == null || lineageEntity.getLineage() == null || lineageEntity.getLineage().getRequest() == null) { @@ -898,13 +1139,41 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Gets a lineage query", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 getLineage( + @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 id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the lineage query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager @@ -954,14 +1223,42 @@ public class ProvenanceResource extends ApplicationResource { * @return A lineageEntity */ @DELETE + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/lineage/{id}") @PreAuthorize("hasRole('ROLE_PROVENANCE')") - @TypeHint(LineageEntity.class) + @ApiOperation( + value = "Deletes a lineage query", + response = LineageEntity.class, + authorizations = { + @Authorization(value = "Provenance", type = "ROLE_PROVENANCE") + } + ) + @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 deleteLineage( @Context HttpServletRequest httpServletRequest, + @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 id of the node where this query exists if clustered.", + required = false + ) @QueryParam("clusterNodeId") String clusterNodeId, + @ApiParam( + value = "The id of the lineage query.", + required = true + ) @PathParam("id") String id) { // replicate if cluster manager
