This is an automated email from the ASF dual-hosted git repository.
baodi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 9d9b8dfa16d [fix][admin][part-1]Clearly define REST API on Open API
(#22774)
9d9b8dfa16d is described below
commit 9d9b8dfa16d2f15142ea94467c086c016cb9e49d
Author: Baodi Shi <ba...@apache.org>
AuthorDate: Sun May 26 10:59:10 2024 +0800
[fix][admin][part-1]Clearly define REST API on Open API (#22774)
---
.../pulsar/broker/admin/impl/BrokerStatsBase.java | 3 +++
.../apache/pulsar/broker/admin/impl/BrokersBase.java | 19 +++++++++++--------
.../apache/pulsar/broker/admin/impl/ClustersBase.java | 10 +++++++---
.../org/apache/pulsar/broker/admin/v2/Bookies.java | 16 +++++++++++++---
.../apache/pulsar/broker/admin/v2/BrokerStats.java | 7 ++++++-
5 files changed, 40 insertions(+), 15 deletions(-)
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokerStatsBase.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokerStatsBase.java
index 6d49dd81da1..48577fc7014 100644
---
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokerStatsBase.java
+++
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokerStatsBase.java
@@ -125,6 +125,9 @@ public class BrokerStatsBase extends AdminResource {
@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
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokersBase.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokersBase.java
index 83067e9f296..7eeea66db71 100644
---
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokersBase.java
+++
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/BrokersBase.java
@@ -219,7 +219,7 @@ public class BrokersBase extends AdminResource {
@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 class BrokersBase extends AdminResource {
@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 class BrokersBase extends AdminResource {
@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 class BrokersBase extends AdminResource {
@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 class BrokersBase extends AdminResource {
@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 class BrokersBase extends AdminResource {
@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 @@ public class BrokersBase extends AdminResource {
@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();
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java
index 2f064d7b377..6eb324a63f3 100644
---
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java
+++
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/ClustersBase.java
@@ -133,7 +133,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -199,7 +199,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -292,7 +292,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -692,6 +692,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -802,6 +803,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -849,6 +851,7 @@ public class ClustersBase extends AdminResource {
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."),
@@ -984,6 +987,7 @@ public class ClustersBase extends AdminResource {
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"),
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java
index 537c886c5d3..c7b09ca9b0a 100644
--- a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java
+++ b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Bookies.java
@@ -20,6 +20,7 @@ package org.apache.pulsar.broker.admin.v2;
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 class Bookies extends AdminResource {
@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 class Bookies extends AdminResource {
@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) {
diff --git
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/BrokerStats.java
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/BrokerStats.java
index aba6cb1a0ab..6f280e8d197 100644
---
a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/BrokerStats.java
+++
b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/BrokerStats.java
@@ -61,7 +61,12 @@ public class BrokerStats extends BrokerStatsBase {
+ "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) {
