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/ControllerResource.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/ControllerResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerResource.java index 9e34201..4883721 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerResource.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.util.HashMap; @@ -74,13 +80,16 @@ import org.apache.nifi.web.api.request.LongParameter; import org.apache.commons.lang3.StringUtils; import org.apache.nifi.web.api.entity.ControllerServiceTypesEntity; import org.apache.nifi.web.api.entity.ReportingTaskTypesEntity; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Flow Controller. */ @Path("/controller") +@Api( + value = "/controller", + description = "Provides realtime command and control of this NiFi instance" +) public class ControllerResource extends ApplicationResource { private NiFiServiceFacade serviceFacade; @@ -96,6 +105,10 @@ public class ControllerResource extends ApplicationResource { * @return the Provenance sub-resource */ @Path("/provenance") + @ApiOperation( + value = "Gets the provenance resource", + response = ProvenanceResource.class + ) public ProvenanceResource getProvenanceResource() { return resourceContext.getResource(ProvenanceResource.class); } @@ -106,6 +119,10 @@ public class ControllerResource extends ApplicationResource { * @return the User sub-resource */ @Path("/users") + @ApiOperation( + value = "Gets the user resource", + response = UserResource.class + ) public UserResource getUserResource() { return resourceContext.getResource(UserResource.class); } @@ -116,6 +133,10 @@ public class ControllerResource extends ApplicationResource { * @return the User sub-resource */ @Path("/user-groups") + @ApiOperation( + value = "Gets the user group resource", + response = UserGroupResource.class + ) public UserGroupResource getUserGroupResource() { return resourceContext.getResource(UserGroupResource.class); } @@ -126,6 +147,10 @@ public class ControllerResource extends ApplicationResource { * @return the History sub-resource */ @Path("/history") + @ApiOperation( + value = "Gets the history resource", + response = HistoryResource.class + ) public HistoryResource getHistoryResource() { return resourceContext.getResource(HistoryResource.class); } @@ -136,6 +161,10 @@ public class ControllerResource extends ApplicationResource { * @return the History sub-resource */ @Path("/bulletin-board") + @ApiOperation( + value = "Gets the bulletin board resource", + response = BulletinBoardResource.class + ) public BulletinBoardResource getBulletinBoardResource() { return resourceContext.getResource(BulletinBoardResource.class); } @@ -146,6 +175,10 @@ public class ControllerResource extends ApplicationResource { * @return the Template sub-resource */ @Path("/templates") + @ApiOperation( + value = "Gets the template resource", + response = TemplateResource.class + ) public TemplateResource getTemplateResource() { return resourceContext.getResource(TemplateResource.class); } @@ -156,6 +189,10 @@ public class ControllerResource extends ApplicationResource { * @return the Snippets sub-resource */ @Path("/snippets") + @ApiOperation( + value = "Gets the snippet resource", + response = SnippetResource.class + ) public SnippetResource getSnippetResource() { return resourceContext.getResource(SnippetResource.class); } @@ -166,6 +203,10 @@ public class ControllerResource extends ApplicationResource { * @return the Controller Services sub-resource */ @Path("/controller-services") + @ApiOperation( + value = "Gets the controller service resource", + response = ControllerServiceResource.class + ) public ControllerServiceResource getControllerServiceResource() { return resourceContext.getResource(ControllerServiceResource.class); } @@ -176,6 +217,10 @@ public class ControllerResource extends ApplicationResource { * @return the Reporting Tasks sub-resource */ @Path("/reporting-tasks") + @ApiOperation( + value = "Gets the reporting task resource", + response = ReportingTaskResource.class + ) public ReportingTaskResource getReportingTaskResource() { return resourceContext.getResource(ReportingTaskResource.class); } @@ -187,7 +232,17 @@ public class ControllerResource extends ApplicationResource { * @return the Group sub-resource */ @Path("/process-groups/{process-group-id}") - public ProcessGroupResource getGroupResource(@PathParam("process-group-id") String groupId) { + @ApiOperation( + value = "Gets the process group resource", + response = ProcessGroupResource.class + ) + public ProcessGroupResource getGroupResource( + @ApiParam( + value = "The id of the process group that is the parent of the requested resource(s). If the desired process group is " + + "the root group an alias 'root' may be used as the process-group-id.", + required = true + ) + @PathParam("process-group-id") String groupId) { ProcessGroupResource groupResource = resourceContext.getResource(ProcessGroupResource.class); groupResource.setGroupId(groupId); return groupResource; @@ -215,10 +270,28 @@ public class ControllerResource extends ApplicationResource { * @return A controllerEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @PreAuthorize("hasRole('ROLE_NIFI')") - @TypeHint(ControllerEntity.class) - public Response getController(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Returns the details about this NiFi necessary to communicate via site to site", + response = ControllerEntity.class, + authorizations = @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 = 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 getController( + @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) { if (properties.isClusterManager()) { return clusterManager.applyRequest(HttpMethod.GET, getAbsolutePath(), getRequestParameters(true), getHeaders()).getResponse(); @@ -247,10 +320,27 @@ public class ControllerResource extends ApplicationResource { * @return A searchResultsEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/search-results") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(SearchResultsEntity.class) + @ApiOperation( + value = "Performs a search against this NiFi using the specified search term", + response = SearchResultsEntity.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 searchController(@QueryParam("q") @DefaultValue(StringUtils.EMPTY) String value) { // replicate if cluster manager if (properties.isClusterManager()) { @@ -284,10 +374,36 @@ public class ControllerResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/archive") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ProcessGroupEntity.class) + @ApiOperation( + value = "Creates a new archive of this NiFi flow configuration", + notes = "This POST operation returns a URI that is not representative of the thing " + + "that was actually created. The archive that is created cannot be referenced " + + "at a later time, therefore there is no corresponding URI. Instead the " + + "request URI is returned.", + 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 = 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 createArchive( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "The revision is used to verify the client is working with the latest version of the flow.", + required = true + ) @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) { // replicate if cluster manager @@ -331,10 +447,35 @@ public class ControllerResource extends ApplicationResource { * @return A revisionEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/revision") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(Entity.class) + @ApiOperation( + value = "Gets the current revision of this NiFi", + notes = "NiFi employs an optimistic locking strategy where the client must include a revision in their request when " + + "performing an update. If the specified revision does not match the current base revision a 409 status code " + + "is returned. The revision is comprised of a clientId and a version number. The version is a simple integer " + + "value that is incremented with each change. Including the most recent version tells NiFi that your working " + + "with the most recent flow. In addition to the version the client who is performing the updates is recorded. " + + "This allows the same client to submit multiple requests without having to wait for the previously ones to " + + "return. Invoking this endpoint will return the current base revision. It is also available when retrieving " + + "a process group and in the response of all mutable requests.", + response = Entity.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 getRevision() { // create the current revision final RevisionDTO revision = serviceFacade.getRevision(); @@ -354,11 +495,33 @@ public class ControllerResource extends ApplicationResource { * @return A controllerStatusEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/status") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerStatusEntity.class) - public Response getControllerStatus(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the current status of this NiFi", + response = Entity.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 getControllerStatus( + @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) { final ControllerStatusDTO controllerStatus = serviceFacade.getControllerStatus(); @@ -382,11 +545,33 @@ public class ControllerResource extends ApplicationResource { * @return A countersEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/counters") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(CountersEntity.class) - public Response getCounters(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Gets the current counters for this NiFi", + response = Entity.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 getCounters( + @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) { final CountersDTO countersReport = serviceFacade.getCounters(); @@ -412,12 +597,32 @@ public class ControllerResource extends ApplicationResource { * @return A counterEntity. */ @PUT + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/counters/{id}") - @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(CounterEntity.class) + @PreAuthorize("hasRole('ROLE_DFM')") + @ApiOperation( + value = "Updates the specified counter. This will reset the counter value to 0", + response = CounterEntity.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 updateCounter( @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, @PathParam("id") String id) { @@ -455,11 +660,35 @@ public class ControllerResource extends ApplicationResource { * @return A controllerConfigurationEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/config") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN', 'ROLE_NIFI')") - @TypeHint(ControllerConfigurationEntity.class) - public Response getControllerConfig(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the configuration for this NiFi", + response = ControllerConfigurationEntity.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 = "ROLE_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 = 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 getControllerConfig( + @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(); @@ -498,7 +727,6 @@ public class ControllerResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/config") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerConfigurationEntity.class) public Response updateControllerConfig( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -550,10 +778,27 @@ public class ControllerResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/config") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerConfigurationEntity.class) + @ApiOperation( + value = "Retrieves the configuration for this NiFi", + response = ControllerConfigurationEntity.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 = 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 updateControllerConfig( @Context HttpServletRequest httpServletRequest, - ControllerConfigurationEntity configEntity) { + @ApiParam( + value = "The controller configuration.", + required = true + ) ControllerConfigurationEntity configEntity) { if (configEntity == null || configEntity.getConfig() == null) { throw new IllegalArgumentException("Controller configuration must be specified"); @@ -606,11 +851,34 @@ public class ControllerResource extends ApplicationResource { * @return A authoritiesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/authorities") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(AuthorityEntity.class) - public Response getAuthorities(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the user details, including the authorities, about the user making the request", + response = AuthorityEntity.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 getAuthorities( + @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) { + // note that the cluster manager will handle this request directly final NiFiUser user = NiFiUserUtils.getNiFiUser(); if (user == null) { @@ -638,11 +906,33 @@ public class ControllerResource extends ApplicationResource { * @return A bannerEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/banners") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(BannerEntity.class) - public Response getBanners(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the banners for this NiFi", + response = BannerEntity.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 getBanners( + @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()) { @@ -676,11 +966,33 @@ public class ControllerResource extends ApplicationResource { * @return A processorTypesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/processor-types") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ProcessorTypesEntity.class) - public Response getProcessorTypes(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the types of processors that this NiFi supports", + response = ProcessorTypesEntity.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 getProcessorTypes( + @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()) { @@ -708,12 +1020,37 @@ public class ControllerResource extends ApplicationResource { * @return A controllerServicesTypesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/controller-service-types") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerServiceTypesEntity.class) + @ApiOperation( + value = "Retrieves the types of controller services that this NiFi supports", + response = ControllerServiceTypesEntity.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 getControllerServiceTypes( + @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 = "If specified, will only return controller services of this type.", + required = false + ) @QueryParam("serviceType") String serviceType) { // replicate if cluster manager @@ -741,11 +1078,33 @@ public class ControllerResource extends ApplicationResource { * @return A controllerServicesTypesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/reporting-task-types") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ReportingTaskTypesEntity.class) - public Response getReportingTaskTypes(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the types of reporting tasks that this NiFi supports", + response = ReportingTaskTypesEntity.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 getReportingTaskTypes( + @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()) { @@ -772,11 +1131,33 @@ public class ControllerResource extends ApplicationResource { * @return A prioritizerTypesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/prioritizers") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(PrioritizerTypesEntity.class) - public Response getPrioritizers(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves the types of prioritizers that this NiFi supports", + response = PrioritizerTypesEntity.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 getPrioritizers( + @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()) { @@ -803,11 +1184,33 @@ public class ControllerResource extends ApplicationResource { * @return An aboutEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/about") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(AboutEntity.class) - public Response getAboutInfo(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId) { + @ApiOperation( + value = "Retrieves details about this NiFi to put in the About dialog", + response = AboutEntity.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 getAboutInfo( + @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()) {
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/ControllerServiceResource.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/ControllerServiceResource.java b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java index 90d031d..2a68015 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.java +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/ControllerServiceResource.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; @@ -66,7 +72,6 @@ import org.apache.nifi.web.api.entity.ControllerServiceReferencingComponentsEnti import org.apache.nifi.web.api.entity.ControllerServicesEntity; import org.apache.nifi.web.api.entity.PropertyDescriptorEntity; import org.apache.nifi.web.util.Availability; -import org.codehaus.enunciate.jaxrs.TypeHint; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.security.access.prepost.PreAuthorize; @@ -74,6 +79,7 @@ import org.springframework.security.access.prepost.PreAuthorize; /** * RESTful endpoint for managing a Controller Service. */ +@Api(hidden = true) public class ControllerServiceResource extends ApplicationResource { private static final Logger logger = LoggerFactory.getLogger(ControllerServiceResource.class); @@ -121,7 +127,8 @@ public class ControllerServiceResource extends ApplicationResource { } /** - * Parses the availability and ensure that the specified availability makes sense for the given NiFi instance. + * Parses the availability and ensure that the specified availability makes + * sense for the given NiFi instance. * * @param availability avail * @return avail @@ -145,17 +152,49 @@ public class ControllerServiceResource extends ApplicationResource { /** * Retrieves all the of controller services 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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @return A controllerServicesEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerServicesEntity.class) - public Response getControllerServices(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("availability") String availability) { + @ApiOperation( + value = "Gets all controller services", + response = ControllerServicesEntity.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 getControllerServices( + @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 controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability) { + final Availability avail = parseAvailability(availability); // replicate if cluster manager @@ -183,10 +222,14 @@ public class ControllerServiceResource extends ApplicationResource { * Creates a new controller service. * * @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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param type The type of controller service to create. * @return A controllerServiceEntity. */ @@ -195,7 +238,6 @@ public class ControllerServiceResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerServiceEntity.class) public Response createControllerService( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -226,8 +268,9 @@ public class ControllerServiceResource extends ApplicationResource { * Creates a new Controller Service. * * @param httpServletRequest request - * @param availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @param availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param controllerServiceEntity A controllerServiceEntity. * @return A controllerServiceEntity. */ @@ -236,11 +279,33 @@ public class ControllerServiceResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerServiceEntity.class) + @ApiOperation( + value = "Creates a new controller service", + response = ControllerServiceEntity.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 = 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 createControllerService( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) @PathParam("availability") String availability, - ControllerServiceEntity controllerServiceEntity) { + @ApiParam( + value = "The controller service configuration details.", + required = true + ) ControllerServiceEntity controllerServiceEntity) { final Availability avail = parseAvailability(availability); @@ -315,19 +380,55 @@ public class ControllerServiceResource extends ApplicationResource { /** * Retrieves 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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service to retrieve * @return A controllerServiceEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerServiceEntity.class) - public Response getControllerService(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, - @PathParam("availability") String availability, @PathParam("id") String id) { + @ApiOperation( + value = "Gets a controller service", + response = ControllerServiceEntity.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 getControllerService( + @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 controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) + @PathParam("id") String id) { final Availability avail = parseAvailability(availability); @@ -354,20 +455,58 @@ public class ControllerServiceResource extends ApplicationResource { /** * Returns the descriptor for the specified property. * - * @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 availability avail * @param id The id of the controller service. * @param propertyName The property * @return a propertyDescriptorEntity */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}/descriptors") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(PropertyDescriptorEntity.class) + @ApiOperation( + value = "Gets a controller service property descriptor", + 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("availability") String availability, @PathParam("id") String id, + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) + @PathParam("id") String id, + @ApiParam( + value = "The property name to return the descriptor for.", + required = true + ) @QueryParam("propertyName") String propertyName) { final Availability avail = parseAvailability(availability); @@ -401,20 +540,55 @@ public class ControllerServiceResource extends ApplicationResource { /** * Retrieves the references of 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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service to retrieve * @return A controllerServiceEntity. */ @GET + @Consumes(MediaType.WILDCARD) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}/references") @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerServiceEntity.class) + @ApiOperation( + value = "Gets a controller service", + response = ControllerServiceEntity.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 getControllerServiceReferences( + @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("availability") String availability, @PathParam("id") String id) { + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) + @PathParam("id") String id) { final Availability avail = parseAvailability(availability); @@ -442,26 +616,70 @@ public class ControllerServiceResource extends ApplicationResource { * Updates the references of the specified controller service. * * @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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service to retrieve - * @param state Sets the state of referencing components. A value of RUNNING or STOPPED will update referencing schedulable components (Processors and Reporting Tasks). A value of ENABLED or - * DISABLED will update referencing controller services. + * @param state Sets the state of referencing components. A value of RUNNING + * or STOPPED will update referencing schedulable components (Processors and + * Reporting Tasks). A value of ENABLED or DISABLED will update referencing + * controller services. * @return A controllerServiceEntity. */ @PUT @Consumes(MediaType.APPLICATION_FORM_URLENCODED) @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}/references") - @PreAuthorize("hasAnyRole('ROLE_MONITOR', 'ROLE_DFM', 'ROLE_ADMIN')") - @TypeHint(ControllerServiceEntity.class) + @PreAuthorize("hasRole('ROLE_DFM')") + @ApiOperation( + value = "Updates a controller services references", + response = ControllerServiceEntity.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 updateControllerServiceReferences( @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, - @PathParam("availability") String availability, @PathParam("id") String id, + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) + @PathParam("id") String id, + @ApiParam( + value = "The new state of the references for the controller service.", + allowableValues = "ENABLED, DISABLED, RUNNING, STOPPED", + required = true + ) @FormParam("state") @DefaultValue(StringUtils.EMPTY) String state) { // parse the state to determine the desired action @@ -536,18 +754,26 @@ public class ControllerServiceResource extends ApplicationResource { * Updates the specified controller service. * * @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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service to update. * @param name The name of the controller service * @param annotationData The annotation data for the controller service * @param comments The comments for the controller service - * @param state The state of this controller service. Should be ENABLED or DISABLED. - * @param markedForDeletion Array of property names whose value should be removed. - * @param formParams Additionally, the processor properties and styles are specified in the form parameters. Because the property names and styles differ from processor to processor they are - * specified in a map-like fashion: + * @param state The state of this controller service. Should be ENABLED or + * DISABLED. + * @param markedForDeletion Array of property names whose value should be + * removed. + * @param formParams Additionally, the processor properties and styles are + * specified in the form parameters. Because the property names and styles + * differ from processor to processor they are specified in a map-like + * fashion: * <br> * <ul> * <li>properties[required.file.path]=/path/to/file</li> @@ -565,7 +791,6 @@ public class ControllerServiceResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerServiceEntity.class) public Response updateControllerService( @Context HttpServletRequest httpServletRequest, @FormParam(VERSION) LongParameter version, @@ -632,8 +857,9 @@ public class ControllerServiceResource extends ApplicationResource { * Updates the specified a new Controller Service. * * @param httpServletRequest request - * @param availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @param availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service to update. * @param controllerServiceEntity A controllerServiceEntity. * @return A controllerServiceEntity. @@ -643,12 +869,39 @@ public class ControllerServiceResource extends ApplicationResource { @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML}) @Path("/{availability}/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerServiceEntity.class) + @ApiOperation( + value = "Updates a controller service", + response = ControllerServiceEntity.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 updateControllerService( @Context HttpServletRequest httpServletRequest, + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) @PathParam("id") String id, - ControllerServiceEntity controllerServiceEntity) { + @ApiParam( + value = "The controller service configuration details.", + required = true + ) ControllerServiceEntity controllerServiceEntity) { final Availability avail = parseAvailability(availability); @@ -709,23 +962,61 @@ public class ControllerServiceResource extends ApplicationResource { * Removes the specified controller service. * * @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 availability Whether the controller service is available on the NCM only (ncm) or on the nodes only (node). If this instance is not clustered all services should use the node - * availability. + * @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 availability Whether the controller service is available on the + * NCM only (ncm) or on the nodes only (node). If this instance is not + * clustered all services should use the node availability. * @param id The id of the controller service 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("/{availability}/{id}") @PreAuthorize("hasRole('ROLE_DFM')") - @TypeHint(ControllerServiceEntity.class) + @ApiOperation( + value = "Deletes a controller service", + response = ControllerServiceEntity.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 removeControllerService( @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, - @PathParam("availability") String availability, @PathParam("id") String id) { + @ApiParam( + value = "Whether the controller service is available on the NCM or nodes. If the NiFi is standalone the availability should be NODE.", + allowableValues = "NCM, NODE", + required = true + ) + @PathParam("availability") String availability, + @ApiParam( + value = "The controller service id.", + required = true + ) + @PathParam("id") String id) { final Availability avail = parseAvailability(availability);
