Repository: incubator-nifi Updated Branches: refs/heads/NIFI-292 d9d3406c2 -> 0e176b5b9
NIFI-292: - Continuing to document/annotate REST resources. - Continuing to template the REST documentation. Project: http://git-wip-us.apache.org/repos/asf/incubator-nifi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-nifi/commit/0e176b5b Tree: http://git-wip-us.apache.org/repos/asf/incubator-nifi/tree/0e176b5b Diff: http://git-wip-us.apache.org/repos/asf/incubator-nifi/diff/0e176b5b Branch: refs/heads/NIFI-292 Commit: 0e176b5b923bf92e1a29a6cd2f4fea6245f02cd0 Parents: d9d3406 Author: Matt Gilman <[email protected]> Authored: Tue Apr 28 13:00:22 2015 -0400 Committer: Matt Gilman <[email protected]> Committed: Tue Apr 28 13:00:22 2015 -0400 ---------------------------------------------------------------------- .../apache/nifi/web/api/ProcessorResource.java | 108 ++++++++++++++++++- .../src/main/resources/templates/example.hbs | 2 +- .../src/main/resources/templates/index.html.hbs | 5 + 3 files changed, 109 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/0e176b5b/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 9aaced1..67aad17 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 @@ -155,6 +155,7 @@ 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')") @@ -368,12 +369,13 @@ 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) @ApiOperation( - value = "Gets the specified processor", + value = "Gets a processor", response = ProcessorEntity.class, authorizations = { @Authorization(value = "Read Only", type = "ROLE_MONITOR"), @@ -390,7 +392,17 @@ public class ProcessorResource extends ApplicationResource { @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(@QueryParam(CLIENT_ID) @DefaultValue(StringUtils.EMPTY) ClientIdParameter clientId, @PathParam("id") String id) { + 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()) { @@ -421,11 +433,40 @@ 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()) { @@ -457,13 +498,45 @@ 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) { @@ -659,9 +732,33 @@ public class ProcessorResource extends ApplicationResource { @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) { @@ -737,12 +834,13 @@ 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 the specified processor", + value = "Deletes a processor", response = ProcessorEntity.class, authorizations = { @Authorization(value = "Data Flow Manager", type = "ROLE_DFM") http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/0e176b5b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/example.hbs ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/example.hbs b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/example.hbs index a753cc3..835c4b5 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/example.hbs +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/example.hbs @@ -12,5 +12,5 @@ See the License for the specific language governing permissions and limitations under the License. --}} -{{#each properties}} {{#ifeq type "string"}}"{{@key}}": "string"{{/ifeq}}{{#ifeq type "integer"}}"{{@key}}": 0{{/ifeq}}{{#if $ref}}"{{@key}}": <span class="nested collapsed"><span class="nested-id hidden">{{basename $ref}}</span><span class="nested-example">{…}</span></span>{{/if}} +{{#each properties}} {{#ifeq type "string"}}"{{@key}}": "value"{{/ifeq}}{{#ifeq type "boolean"}}"{{@key}}": true{{/ifeq}}{{#ifeq type "integer"}}"{{@key}}": 0{{/ifeq}}{{#if $ref}}"{{@key}}": <span class="nested collapsed"><span class="nested-id hidden">{{basename $ref}}</span><span class="nested-example">{…}</span></span>{{/if}}{{#ifeq type "array"}}"{{@key}}": [{{#if items.$ref}}<span class="nested collapsed"><span class="nested-id hidden">{{basename items.$ref}}</span><span class="nested-example">{…}</span></span>{{else}}{{items.type}}{{/if}}]{{/ifeq}}{{#ifeq type "object"}}"{{@key}}": {{{#if additionalProperties.$ref}}<span class="nested collapsed"><span class="nested-id hidden">{{basename additionalProperties.$ref}}</span><span class="nested-example">{…}</span></span>{{else}}{{#ifeq additionalProperties.type "integer"}}0{{else}}"value"{{/ifeq}}{{/if}}}{{/ifeq}}<span class="comma">,</span> {{/each}} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-nifi/blob/0e176b5b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs ---------------------------------------------------------------------- diff --git a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs index 3516247..ec4cec4 100644 --- a/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs +++ b/nifi/nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs @@ -314,6 +314,11 @@ e.stopPropagation(); }); + // due to lack of support for @last when iterating objects + // in handlebars we need to remove the last comma from each + // example + $('code.example').find('span.comma:last').remove(); + // populate nested examples $('code.example').on('click', 'span.nested', function(e) { var nested = $(this).removeClass('collapsed');
