NIFI-4855:

- Fix the layout of NiFi API document
- update the sub-title to be more detailed
- This closes #2503

nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/java/org/apache/nifi/web/api/VersionsResource.java

@@ -175,11 +175,12 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.TEXT_PLAIN)
     @Path("active-requests")
     @ApiOperation(
-        value = "Creates a request so that a Process Group can be placed under Version Control or have its Version Control configuration changed. Creating this request will "
-            + "prevent any other threads from simultaneously saving local changes to Version Control. It will not, however, actually save the local flow to the Flow Registry. A "
-            + "POST to /versions/process-groups/{id} should be used to initiate saving of the local flow to the Flow Registry.",
+        value = "Create a version control request",
             response = String.class,
-        notes = NON_GUARANTEED_ENDPOINT,
+        notes = "Creates a request so that a Process Group can be placed under Version Control or have its Version Control configuration changed. Creating this request will "
+            + "prevent any other threads from simultaneously saving local changes to Version Control. It will not, however, actually save the local flow to the Flow Registry. A "
+            + "POST to /versions/process-groups/{id} should be used to initiate saving of the local flow to the Flow Registry. "
+            + NON_GUARANTEED_ENDPOINT,
         authorizations = {
             @Authorization(value = "Write - /process-groups/{uuid}")
         })
@@ -348,9 +349,10 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("active-requests/{id}")
     @ApiOperation(
-            value = "Deletes the Version Control Request with the given ID. This will allow other threads to save flows to the Flow Registry. See also the documentation "
-                + "for POSTing to /versions/active-requests for information regarding why this is done.",
-            notes = NON_GUARANTEED_ENDPOINT,
+            value = "Deletes the version control request with the given ID",
+            notes = "Deletes the Version Control Request with the given ID. This will allow other threads to save flows to the Flow Registry. See also the documentation "
+                + "for POSTing to /versions/active-requests for information regarding why this is done. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Only the user that submitted the request can remove it")
             })
@@ -404,10 +406,11 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("process-groups/{id}")
     @ApiOperation(
-            value = "Begins version controlling the Process Group with the given ID or commits changes to the Versioned Flow, "
-                + "depending on if the provided VersionControlInformation includes a flowId",
+            value = "Save the Process Group with the given ID",
             response = VersionControlInformationEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Begins version controlling the Process Group with the given ID or commits changes to the Versioned Flow, "
+                + "depending on if the provided VersionControlInformation includes a flowId. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Read - /process-groups/{uuid}"),
                 @Authorization(value = "Write - /process-groups/{uuid}"),
@@ -644,9 +647,10 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("process-groups/{id}")
     @ApiOperation(
-            value = "Stops version controlling the Process Group with the given ID. The Process Group will no longer track to any Versioned Flow.",
+            value = "Stops version controlling the Process Group with the given ID",
             response = VersionControlInformationEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Stops version controlling the Process Group with the given ID. The Process Group will no longer track to any Versioned Flow. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Read - /process-groups/{uuid}"),
                 @Authorization(value = "Write - /process-groups/{uuid}"),
@@ -704,10 +708,11 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("process-groups/{id}")
     @ApiOperation(
-            value = "For a Process Group that is already under Version Control, this will update the version of the flow to a different version. This endpoint expects "
-                + "that the given snapshot will not modify any Processor that is currently running or any Controller Service that is enabled.",
+            value = "Update the version of a Process Group with the given ID",
             response = VersionControlInformationEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "For a Process Group that is already under Version Control, this will update the version of the flow to a different version. This endpoint expects "
+                + "that the given snapshot will not modify any Processor that is currently running or any Controller Service that is enabled. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Read - /process-groups/{uuid}"),
                 @Authorization(value = "Write - /process-groups/{uuid}")
@@ -808,11 +813,12 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("update-requests/{id}")
     @ApiOperation(
-            value = "Returns the Update Request with the given ID. Once an Update Request has been created by performing a POST to /versions/update-requests/process-groups/{id}, "
-                + "that request can subsequently be retrieved via this endpoint, and the request that is fetched will contain the updated state, such as percent complete, the "
-                + "current state of the request, and any failures.",
+            value = "Returns the Update Request with the given ID",
             response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Returns the Update Request with the given ID. Once an Update Request has been created by performing a POST to /versions/update-requests/process-groups/{id}, "
+                + "that request can subsequently be retrieved via this endpoint, and the request that is fetched will contain the updated state, such as percent complete, the "
+                + "current state of the request, and any failures. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Only the user that submitted the request can get it")
             })
@@ -832,11 +838,12 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("revert-requests/{id}")
     @ApiOperation(
-            value = "Returns the Revert Request with the given ID. Once a Revert Request has been created by performing a POST to /versions/revert-requests/process-groups/{id}, "
-                + "that request can subsequently be retrieved via this endpoint, and the request that is fetched will contain the updated state, such as percent complete, the "
-                + "current state of the request, and any failures.",
+            value = "Returns the Revert Request with the given ID",
             response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Returns the Revert Request with the given ID. Once a Revert Request has been created by performing a POST to /versions/revert-requests/process-groups/{id}, "
+                + "that request can subsequently be retrieved via this endpoint, and the request that is fetched will contain the updated state, such as percent complete, the "
+                + "current state of the request, and any failures. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Only the user that submitted the request can get it")
             })
@@ -890,11 +897,12 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("update-requests/{id}")
     @ApiOperation(
-        value = "Deletes the Update Request with the given ID. After a request is created via a POST to /versions/update-requests/process-groups/{id}, it is expected "
-            + "that the client will properly clean up the request by DELETE'ing it, once the Update process has completed. If the request is deleted before the request "
-            + "completes, then the Update request will finish the step that it is currently performing and then will cancel any subsequent steps.",
+            value = "Deletes the Update Request with the given ID",
             response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Deletes the Update Request with the given ID. After a request is created via a POST to /versions/update-requests/process-groups/{id}, it is expected "
+                + "that the client will properly clean up the request by DELETE'ing it, once the Update process has completed. If the request is deleted before the request "
+                + "completes, then the Update request will finish the step that it is currently performing and then will cancel any subsequent steps. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Only the user that submitted the request can remove it")
             })
@@ -914,11 +922,12 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("revert-requests/{id}")
     @ApiOperation(
-            value = "Deletes the Revert Request with the given ID. After a request is created via a POST to /versions/revert-requests/process-groups/{id}, it is expected "
-                + "that the client will properly clean up the request by DELETE'ing it, once the Revert process has completed. If the request is deleted before the request "
-            + "completes, then the Revert request will finish the step that it is currently performing and then will cancel any subsequent steps.",
+            value = "Deletes the Revert Request with the given ID",
             response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+            notes = "Deletes the Revert Request with the given ID. After a request is created via a POST to /versions/revert-requests/process-groups/{id}, it is expected "
+                + "that the client will properly clean up the request by DELETE'ing it, once the Revert process has completed. If the request is deleted before the request "
+                + "completes, then the Revert request will finish the step that it is currently performing and then will cancel any subsequent steps. "
+                + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Only the user that submitted the request can remove it")
             })
@@ -982,15 +991,15 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("update-requests/process-groups/{id}")
     @ApiOperation(
-            value = "For a Process Group that is already under Version Control, this will initiate the action of changing "
+            value = "Initiate the Update Request of a Process Group with the given ID",
+            response = VersionedFlowUpdateRequestEntity.class,
+            notes = "For a Process Group that is already under Version Control, this will initiate the action of changing "
                 + "from a specific version of the flow in the Flow Registry to a different version of the flow. This can be a lengthy "
                 + "process, as it will stop any Processors and disable any Controller Services necessary to perform the action and then restart them. As a result, "
                 + "the endpoint will immediately return a VersionedFlowUpdateRequestEntity, and the process of updating the flow will occur "
                 + "asynchronously in the background. The client may then periodically poll the status of the request by issuing a GET request to "
                 + "/versions/update-requests/{requestId}. Once the request is completed, the client is expected to issue a DELETE request to "
-                + "/versions/update-requests/{requestId}.",
-            response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+                + "/versions/update-requests/{requestId}. " + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Read - /process-groups/{uuid}"),
                 @Authorization(value = "Write - /process-groups/{uuid}"),
@@ -1171,16 +1180,16 @@ public class VersionsResource extends ApplicationResource {
     @Produces(MediaType.APPLICATION_JSON)
     @Path("revert-requests/process-groups/{id}")
     @ApiOperation(
-            value = "For a Process Group that is already under Version Control, this will initiate the action of reverting "
+            value = "Initiate the Revert Request of a Process Group with the given ID",
+            response = VersionedFlowUpdateRequestEntity.class,
+            notes = "For a Process Group that is already under Version Control, this will initiate the action of reverting "
                 + "any local changes that have been made to the Process Group since it was last synchronized with the Flow Registry. This will result in the "
                 + "flow matching the Versioned Flow that exists in the Flow Registry. This can be a lengthy "
                 + "process, as it will stop any Processors and disable any Controller Services necessary to perform the action and then restart them. As a result, "
                 + "the endpoint will immediately return a VersionedFlowUpdateRequestEntity, and the process of updating the flow will occur "
                 + "asynchronously in the background. The client may then periodically poll the status of the request by issuing a GET request to "
                 + "/versions/revert-requests/{requestId}. Once the request is completed, the client is expected to issue a DELETE request to "
-                + "/versions/revert-requests/{requestId}.",
-            response = VersionedFlowUpdateRequestEntity.class,
-            notes = NON_GUARANTEED_ENDPOINT,
+                + "/versions/revert-requests/{requestId}. " + NON_GUARANTEED_ENDPOINT,
             authorizations = {
                 @Authorization(value = "Read - /process-groups/{uuid}"),
                 @Authorization(value = "Write - /process-groups/{uuid}"),

nifi-nar-bundles/nifi-framework-bundle/nifi-framework/nifi-web/nifi-web-api/src/main/resources/templates/index.html.hbs

@@ -457,6 +457,7 @@
                 organizeEndpoints('/snippets', $('#snippet-endpoints'));
                 organizeEndpoints('/system', $('#system-diagnostic-endpoints'));
                 organizeEndpoints('/templates', $('#template-endpoints'));
+                organizeEndpoints('/versions', $('#version-endpoints'));
                 organizeEndpoints(null, $('#controller-endpoints'));
 
                 // handle expanding/collapsing the sections
@@ -675,6 +676,14 @@
             </div>
             <div id="system-diagnostic-endpoints" class="section-endpoints hidden"></div>
         </div>
+        <div class="section">
+            <div class="section-header">
+                <div class="title link">Versions</div>
+                <div class="sub-title section-description">Manage versions of process groups</div>
+                <div class="clear"></div>
+            </div>
+            <div id="version-endpoints" class="section-endpoints hidden"></div>
+        </div>
         <div class="unorganized hidden">
             {{#each paths}}
                 {{> endpoint}}