Skip to content

Commit 6b05ca0

Browse files
shibdshibd
committed
[fix][admin][part-1]Clearly define REST API on Open API (#22774)
(cherry picked from commit 9d9b8df)
1 parent 0771f81 commit 6b05ca0

File tree

5 files changed

+40
-15
lines changed

5 files changed

+40
-15
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,9 @@ public AllocatorStats getAllocatorStats(@PathParam("allocator") String allocator
125125
@GET
126126
@Path("/bookieops")
127127
@ApiOperation(value = "Get pending bookie client op stats by namespace",
128+
notes = "Returns a nested map structure which Swagger does not fully support for display. "
129+
+ "Structure: Map<String, Map<String, PendingBookieOpsStats>>."
130+
+ " Please refer to this structure for details.",
128131
response = PendingBookieOpsStats.class,
129132
// https://github.com/swagger-api/swagger-core/issues/449
130133
// nested containers are not supported

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

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ public void updateDynamicConfiguration(@Suspended AsyncResponse asyncResponse,
219219
@ApiOperation(value =
220220
"Delete dynamic ServiceConfiguration into metadata only."
221221
+ " This operation requires Pulsar super-user privileges.")
222-
@ApiResponses(value = { @ApiResponse(code = 204, message = "Service configuration updated successfully"),
222+
@ApiResponses(value = { @ApiResponse(code = 204, message = "Service configuration delete successfully"),
223223
@ApiResponse(code = 403, message = "You don't have admin permission to update service-configuration"),
224224
@ApiResponse(code = 412, message = "Invalid dynamic-config value"),
225225
@ApiResponse(code = 500, message = "Internal server error") })
@@ -240,7 +240,8 @@ public void deleteDynamicConfiguration(
240240

241241
@GET
242242
@Path("/configuration/values")
243-
@ApiOperation(value = "Get value of all dynamic configurations' value overridden on local config")
243+
@ApiOperation(value = "Get value of all dynamic configurations' value overridden on local config",
244+
response = String.class, responseContainer = "Map")
244245
@ApiResponses(value = {
245246
@ApiResponse(code = 403, message = "You don't have admin permission to view configuration"),
246247
@ApiResponse(code = 404, message = "Configuration not found"),
@@ -258,7 +259,8 @@ public void getAllDynamicConfigurations(@Suspended AsyncResponse asyncResponse)
258259

259260
@GET
260261
@Path("/configuration")
261-
@ApiOperation(value = "Get all updatable dynamic configurations's name")
262+
@ApiOperation(value = "Get all updatable dynamic configurations's name",
263+
response = String.class, responseContainer = "List")
262264
@ApiResponses(value = {
263265
@ApiResponse(code = 403, message = "You don't have admin permission to get configuration")})
264266
public void getDynamicConfigurationName(@Suspended AsyncResponse asyncResponse) {
@@ -273,7 +275,8 @@ public void getDynamicConfigurationName(@Suspended AsyncResponse asyncResponse)
273275

274276
@GET
275277
@Path("/configuration/runtime")
276-
@ApiOperation(value = "Get all runtime configurations. This operation requires Pulsar super-user privileges.")
278+
@ApiOperation(value = "Get all runtime configurations. This operation requires Pulsar super-user privileges.",
279+
response = String.class, responseContainer = "Map")
277280
@ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission") })
278281
public void getRuntimeConfiguration(@Suspended AsyncResponse asyncResponse) {
279282
validateSuperUserAccessAsync()
@@ -330,7 +333,7 @@ public void getInternalConfigurationData(@Suspended AsyncResponse asyncResponse)
330333
@Path("/backlog-quota-check")
331334
@ApiOperation(value = "An REST endpoint to trigger backlogQuotaCheck")
332335
@ApiResponses(value = {
333-
@ApiResponse(code = 200, message = "Everything is OK"),
336+
@ApiResponse(code = 204, message = "Everything is OK"),
334337
@ApiResponse(code = 403, message = "Don't have admin permission"),
335338
@ApiResponse(code = 500, message = "Internal server error")})
336339
public void backlogQuotaCheck(@Suspended AsyncResponse asyncResponse) {
@@ -368,15 +371,15 @@ public void isReady(@Suspended AsyncResponse asyncResponse) {
368371
@ApiResponse(code = 403, message = "Don't have admin permission"),
369372
@ApiResponse(code = 404, message = "Cluster doesn't exist"),
370373
@ApiResponse(code = 500, message = "Internal server error")})
371-
@ApiParam(value = "Topic Version")
372374
public void healthCheck(@Suspended AsyncResponse asyncResponse,
375+
@ApiParam(value = "Topic Version")
373376
@QueryParam("topicVersion") TopicVersion topicVersion) {
374377
validateSuperUserAccessAsync()
375378
.thenAccept(__ -> checkDeadlockedThreads())
376379
.thenCompose(__ -> internalRunHealthCheck(topicVersion))
377380
.thenAccept(__ -> {
378381
LOG.info("[{}] Successfully run health check.", clientAppId());
379-
asyncResponse.resume("ok");
382+
asyncResponse.resume(Response.ok("ok").build());
380383
}).exceptionally(ex -> {
381384
LOG.error("[{}] Fail to run health check.", clientAppId(), ex);
382385
resumeAsyncResponseExceptionally(asyncResponse, ex);
@@ -541,7 +544,7 @@ private CompletableFuture<Void> internalDeleteDynamicConfigurationOnMetadataAsyn
541544
@Path("/version")
542545
@ApiOperation(value = "Get version of current broker")
543546
@ApiResponses(value = {
544-
@ApiResponse(code = 200, message = "Everything is OK"),
547+
@ApiResponse(code = 200, message = "The Pulsar version", response = String.class),
545548
@ApiResponse(code = 500, message = "Internal server error")})
546549
public String version() throws Exception {
547550
return PulsarVersion.getVersion();

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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,7 @@ public void getCluster(@Suspended AsyncResponse asyncResponse,
133133
notes = "This operation requires Pulsar superuser privileges, and the name cannot contain the '/' characters."
134134
)
135135
@ApiResponses(value = {
136-
@ApiResponse(code = 204, message = "Cluster has been created."),
136+
@ApiResponse(code = 200, message = "Cluster has been created."),
137137
@ApiResponse(code = 400, message = "Bad request parameter."),
138138
@ApiResponse(code = 403, message = "You don't have admin permission to create the cluster."),
139139
@ApiResponse(code = 409, message = "Cluster already exists."),
@@ -199,7 +199,7 @@ public void createCluster(
199199
value = "Update the configuration for a cluster.",
200200
notes = "This operation requires Pulsar superuser privileges.")
201201
@ApiResponses(value = {
202-
@ApiResponse(code = 204, message = "Cluster has been updated."),
202+
@ApiResponse(code = 200, message = "Cluster has been updated."),
203203
@ApiResponse(code = 400, message = "Bad request parameter."),
204204
@ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
205205
@ApiResponse(code = 404, message = "Cluster doesn't exist."),
@@ -292,7 +292,7 @@ public void getClusterMigration(
292292
value = "Update the configuration for a cluster migration.",
293293
notes = "This operation requires Pulsar superuser privileges.")
294294
@ApiResponses(value = {
295-
@ApiResponse(code = 204, message = "Cluster has been updated."),
295+
@ApiResponse(code = 200, message = "Cluster has been updated."),
296296
@ApiResponse(code = 400, message = "Cluster url must not be empty."),
297297
@ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
298298
@ApiResponse(code = 404, message = "Cluster doesn't exist."),
@@ -692,6 +692,7 @@ public void getBrokerWithNamespaceIsolationPolicy(
692692
notes = "This operation requires Pulsar superuser privileges."
693693
)
694694
@ApiResponses(value = {
695+
@ApiResponse(code = 204, message = "Set namespace isolation policy successfully."),
695696
@ApiResponse(code = 400, message = "Namespace isolation policy data is invalid."),
696697
@ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
697698
@ApiResponse(code = 404, message = "Namespace isolation policy doesn't exist."),
@@ -802,6 +803,7 @@ private CompletableFuture<Void> filterAndUnloadMatchedNamespaceAsync(NamespaceIs
802803
notes = "This operation requires Pulsar superuser privileges."
803804
)
804805
@ApiResponses(value = {
806+
@ApiResponse(code = 204, message = "Delete namespace isolation policy successfully."),
805807
@ApiResponse(code = 403, message = "Don't have admin permission or policies are read only."),
806808
@ApiResponse(code = 404, message = "Namespace isolation policy doesn't exist."),
807809
@ApiResponse(code = 412, message = "Cluster doesn't exist."),
@@ -849,6 +851,7 @@ public void deleteNamespaceIsolationPolicy(
849851
notes = "This operation requires Pulsar superuser privileges."
850852
)
851853
@ApiResponses(value = {
854+
@ApiResponse(code = 204, message = "Set the failure domain of the cluster successfully."),
852855
@ApiResponse(code = 403, message = "Don't have admin permission."),
853856
@ApiResponse(code = 404, message = "Failure domain doesn't exist."),
854857
@ApiResponse(code = 409, message = "Broker already exists in another domain."),
@@ -984,6 +987,7 @@ public void getDomain(
984987
notes = "This operation requires Pulsar superuser privileges."
985988
)
986989
@ApiResponses(value = {
990+
@ApiResponse(code = 200, message = "Delete the failure domain of the cluster successfully"),
987991
@ApiResponse(code = 403, message = "Don't have admin permission or policy is read only"),
988992
@ApiResponse(code = 404, message = "FailureDomain doesn't exist"),
989993
@ApiResponse(code = 412, message = "Cluster doesn't exist"),

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

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020

2121
import io.swagger.annotations.Api;
2222
import io.swagger.annotations.ApiOperation;
23+
import io.swagger.annotations.ApiParam;
2324
import io.swagger.annotations.ApiResponse;
2425
import io.swagger.annotations.ApiResponses;
2526
import java.util.ArrayList;
@@ -124,7 +125,10 @@ public void getBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
124125
@DELETE
125126
@Path("/racks-info/{bookie}")
126127
@ApiOperation(value = "Removed the rack placement information for a specific bookie in the cluster")
127-
@ApiResponses(value = {@ApiResponse(code = 403, message = "Don't have admin permission")})
128+
@ApiResponses(value = {
129+
@ApiResponse(code = 204, message = "Operation successful"),
130+
@ApiResponse(code = 403, message = "Don't have admin permission")
131+
})
128132
public void deleteBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
129133
@PathParam("bookie") String bookieAddress) throws Exception {
130134
validateSuperUserAccess();
@@ -153,11 +157,17 @@ public void deleteBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
153157
@Path("/racks-info/{bookie}")
154158
@ApiOperation(value = "Updates the rack placement information for a specific bookie in the cluster (note."
155159
+ " bookie address format:`address:port`)")
156-
@ApiResponses(value = {@ApiResponse(code = 403, message = "Don't have admin permission")})
160+
@ApiResponses(value = {
161+
@ApiResponse(code = 204, message = "Operation successful"),
162+
@ApiResponse(code = 403, message = "Don't have admin permission")}
163+
)
157164
public void updateBookieRackInfo(@Suspended final AsyncResponse asyncResponse,
165+
@ApiParam(value = "The bookie address", required = true)
158166
@PathParam("bookie") String bookieAddress,
167+
@ApiParam(value = "The group", required = true)
159168
@QueryParam("group") String group,
160-
BookieInfo bookieInfo) throws Exception {
169+
@ApiParam(value = "The bookie info", required = true)
170+
BookieInfo bookieInfo) throws Exception {
161171
validateSuperUserAccess();
162172

163173
if (group == null) {

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

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

0 commit comments

Comments
 (0)