[fix][admin][part-1]Clearly define REST API on Open API (apache#22774)

(cherry picked from commit 9d9b8df)

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokerStatsBase.java

@@ -125,6 +125,9 @@ public AllocatorStats getAllocatorStats(@PathParam("allocator") String allocator
     @GET
     @Path("/bookieops")
     @ApiOperation(value = "Get pending bookie client op stats by namespace",
+            notes = "Returns a nested map structure which Swagger does not fully support for display. "
+                    + "Structure: Map<String, Map<String, PendingBookieOpsStats>>."
+                    + " Please refer to this structure for details.",
             response = PendingBookieOpsStats.class,
             // https://github.com/swagger-api/swagger-core/issues/449
             // nested containers are not supported

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokersBase.java

@@ -219,7 +219,7 @@ public void updateDynamicConfiguration(@Suspended AsyncResponse asyncResponse,
     @ApiOperation(value =
             "Delete dynamic ServiceConfiguration into metadata only."
                     + " This operation requires Pulsar super-user privileges.")
-    @ApiResponses(value = { @ApiResponse(code = 204, message = "Service configuration updated successfully"),
+    @ApiResponses(value = { @ApiResponse(code = 204, message = "Service configuration delete successfully"),
             @ApiResponse(code = 403, message = "You don't have admin permission to update service-configuration"),
             @ApiResponse(code = 412, message = "Invalid dynamic-config value"),
             @ApiResponse(code = 500, message = "Internal server error") })
@@ -240,7 +240,8 @@ public void deleteDynamicConfiguration(
 
     @GET
     @Path("/configuration/values")
-    @ApiOperation(value = "Get value of all dynamic configurations' value overridden on local config")
+    @ApiOperation(value = "Get value of all dynamic configurations' value overridden on local config",
+            response = String.class, responseContainer = "Map")
     @ApiResponses(value = {
         @ApiResponse(code = 403, message = "You don't have admin permission to view configuration"),
         @ApiResponse(code = 404, message = "Configuration not found"),
@@ -258,7 +259,8 @@ public void getAllDynamicConfigurations(@Suspended AsyncResponse asyncResponse)
 
     @GET
     @Path("/configuration")
-    @ApiOperation(value = "Get all updatable dynamic configurations's name")
+    @ApiOperation(value = "Get all updatable dynamic configurations's name",
+            response = String.class, responseContainer = "List")
     @ApiResponses(value = {
             @ApiResponse(code = 403, message = "You don't have admin permission to get configuration")})
     public void getDynamicConfigurationName(@Suspended AsyncResponse asyncResponse) {
@@ -273,7 +275,8 @@ public void getDynamicConfigurationName(@Suspended AsyncResponse asyncResponse)
 
     @GET
     @Path("/configuration/runtime")
-    @ApiOperation(value = "Get all runtime configurations. This operation requires Pulsar super-user privileges.")
+    @ApiOperation(value = "Get all runtime configurations. This operation requires Pulsar super-user privileges.",
+            response = String.class, responseContainer = "Map")
     @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission") })
     public void getRuntimeConfiguration(@Suspended AsyncResponse asyncResponse) {
         validateSuperUserAccessAsync()
@@ -330,7 +333,7 @@ public void getInternalConfigurationData(@Suspended AsyncResponse asyncResponse)
     @Path("/backlog-quota-check")
     @ApiOperation(value = "An REST endpoint to trigger backlogQuotaCheck")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Everything is OK"),
+            @ApiResponse(code = 204, message = "Everything is OK"),
             @ApiResponse(code = 403, message = "Don't have admin permission"),
             @ApiResponse(code = 500, message = "Internal server error")})
     public void backlogQuotaCheck(@Suspended AsyncResponse asyncResponse) {
@@ -368,15 +371,15 @@ public void isReady(@Suspended AsyncResponse asyncResponse) {
         @ApiResponse(code = 403, message = "Don't have admin permission"),
         @ApiResponse(code = 404, message = "Cluster doesn't exist"),
         @ApiResponse(code = 500, message = "Internal server error")})
-    @ApiParam(value = "Topic Version")
     public void healthCheck(@Suspended AsyncResponse asyncResponse,
+                            @ApiParam(value = "Topic Version")
                             @QueryParam("topicVersion") TopicVersion topicVersion) {
         validateSuperUserAccessAsync()
                 .thenAccept(__ -> checkDeadlockedThreads())
                 .thenCompose(__ -> internalRunHealthCheck(topicVersion))
                 .thenAccept(__ -> {
                     LOG.info("[{}] Successfully run health check.", clientAppId());
-                    asyncResponse.resume("ok");
+                    asyncResponse.resume(Response.ok("ok").build());
                 }).exceptionally(ex -> {
                     LOG.error("[{}] Fail to run health check.", clientAppId(), ex);
                     resumeAsyncResponseExceptionally(asyncResponse, ex);
@@ -541,7 +544,7 @@ private CompletableFuture<Void> internalDeleteDynamicConfigurationOnMetadataAsyn
     @Path("/version")
     @ApiOperation(value = "Get version of current broker")
     @ApiResponses(value = {
-            @ApiResponse(code = 200, message = "Everything is OK"),
+            @ApiResponse(code = 200, message = "The Pulsar version", response = String.class),
             @ApiResponse(code = 500, message = "Internal server error")})
     public String version() throws Exception {
         return PulsarVersion.getVersion();

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java

@@ -132,7 +132,7 @@ public void getCluster(@Suspended AsyncResponse asyncResponse,
         notes = "This operation requires Pulsar superuser privileges, and the name cannot contain the '/' characters."
     )
     @ApiResponses(value = {
-            @ApiResponse(code = 204, message = "Cluster has been created."),
+            @ApiResponse(code = 200, message = "Cluster has been created."),
             @ApiResponse(code = 400, message = "Bad request parameter."),
             @ApiResponse(code = 403, message = "You don't have admin permission to create the cluster."),
             @ApiResponse(code = 409, message = "Cluster already exists."),
@@ -198,7 +198,7 @@ public void createCluster(
         value = "Update the configuration for a cluster.",
         notes = "This operation requires Pulsar superuser privileges.")
     @ApiResponses(value = {
-            @ApiResponse(code = 204, message = "Cluster has been updated."),
+            @ApiResponse(code = 200, message = "Cluster has been updated."),
             @ApiResponse(code = 400, message = "Bad request parameter."),
             @ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
             @ApiResponse(code = 404, message = "Cluster doesn't exist."),
@@ -253,7 +253,7 @@ public void updateCluster(
         value = "Update the configuration for a cluster migration.",
         notes = "This operation requires Pulsar superuser privileges.")
     @ApiResponses(value = {
-            @ApiResponse(code = 204, message = "Cluster has been updated."),
+            @ApiResponse(code = 200, message = "Cluster has been updated."),
             @ApiResponse(code = 400, message = "Cluster url must not be empty."),
             @ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
             @ApiResponse(code = 404, message = "Cluster doesn't exist."),
@@ -652,6 +652,7 @@ public void getBrokerWithNamespaceIsolationPolicy(
         notes = "This operation requires Pulsar superuser privileges."
     )
     @ApiResponses(value = {
+        @ApiResponse(code = 204, message = "Set namespace isolation policy successfully."),
         @ApiResponse(code = 400, message = "Namespace isolation policy data is invalid."),
         @ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
         @ApiResponse(code = 404, message = "Namespace isolation policy doesn't exist."),
@@ -762,6 +763,7 @@ private CompletableFuture<Void> filterAndUnloadMatchedNamespaceAsync(NamespaceIs
         notes = "This operation requires Pulsar superuser privileges."
     )
     @ApiResponses(value = {
+        @ApiResponse(code = 204, message = "Delete namespace isolation policy successfully."),
         @ApiResponse(code = 403, message = "Don't have admin permission or policies are read only."),
         @ApiResponse(code = 404, message = "Namespace isolation policy doesn't exist."),
         @ApiResponse(code = 412, message = "Cluster doesn't exist."),
@@ -809,6 +811,7 @@ public void deleteNamespaceIsolationPolicy(
         notes = "This operation requires Pulsar superuser privileges."
     )
     @ApiResponses(value = {
+        @ApiResponse(code = 204, message = "Set the failure domain of the cluster successfully."),
         @ApiResponse(code = 403, message = "Don't have admin permission."),
         @ApiResponse(code = 404, message = "Failure domain doesn't exist."),
         @ApiResponse(code = 409, message = "Broker already exists in another domain."),
@@ -944,6 +947,7 @@ public void getDomain(
         notes = "This operation requires Pulsar superuser privileges."
     )
     @ApiResponses(value = {
+        @ApiResponse(code = 200, message = "Delete the failure domain of the cluster successfully"),
         @ApiResponse(code = 403, message = "Don't have admin permission or policy is read only"),
         @ApiResponse(code = 404, message = "FailureDomain doesn't exist"),
         @ApiResponse(code = 412, message = "Cluster doesn't exist"),

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java

@@ -20,6 +20,7 @@
 
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import io.swagger.annotations.ApiResponse;
 import io.swagger.annotations.ApiResponses;
 import java.util.ArrayList;
@@ -124,7 +125,10 @@ public void getBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
     @DELETE
     @Path("/racks-info/{bookie}")
     @ApiOperation(value = "Removed the rack placement information for a specific bookie in the cluster")
-    @ApiResponses(value = {@ApiResponse(code = 403, message = "Don't have admin permission")})
+    @ApiResponses(value = {
+            @ApiResponse(code = 204, message = "Operation successful"),
+            @ApiResponse(code = 403, message = "Don't have admin permission")
+    })
     public void deleteBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
                                      @PathParam("bookie") String bookieAddress) throws Exception {
         validateSuperUserAccess();
@@ -153,11 +157,17 @@ public void deleteBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
     @Path("/racks-info/{bookie}")
     @ApiOperation(value = "Updates the rack placement information for a specific bookie in the cluster (note."
             + " bookie address format:`address:port`)")
-    @ApiResponses(value = {@ApiResponse(code = 403, message = "Don't have admin permission")})
+    @ApiResponses(value = {
+            @ApiResponse(code = 204, message = "Operation successful"),
+            @ApiResponse(code = 403, message = "Don't have admin permission")}
+    )
     public void updateBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
+                                     @ApiParam(value = "The bookie address", required = true)
                                      @PathParam("bookie") String bookieAddress,
+                                     @ApiParam(value = "The group", required = true)
                                      @QueryParam("group") String group,
-            BookieInfo bookieInfo) throws Exception {
+                                     @ApiParam(value = "The bookie info", required = true)
+                                     BookieInfo bookieInfo) throws Exception {
         validateSuperUserAccess();
 
         if (group == null) {

pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/BrokerStats.java

@@ -61,7 +61,12 @@ public StreamingOutput getTopics2() throws Exception {
             + "sum of all of the resource usage percent is called broker-resource-availability"
             + "<br/><br/>THIS API IS ONLY FOR USE BY TESTING FOR CONFIRMING NAMESPACE ALLOCATION ALGORITHM",
             response = ResourceUnit.class, responseContainer = "Map")
-    @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
+    @ApiResponses(value = {
+            @ApiResponse(code = 200, message = "Returns broker resource availability as Map<Long, List<ResourceUnit>>."
+                    + "Since `ResourceUnit` is an interface, its specific content is not determinable via class "
+                    + "reflection. Refer to the source code or interface tests for detailed type definitions.",
+            response = Map.class),
+            @ApiResponse(code = 403, message = "Don't have admin permission"),
             @ApiResponse(code = 409, message = "Load-manager doesn't support operation") })
     public Map<Long, Collection<ResourceUnit>> getBrokerResourceAvailability(@PathParam("tenant") String tenant,
         @PathParam("namespace") String namespace) {