Skip to content

Commit 7ca884b

Browse files
shibdshibd
committed
[fix][admin] Clearly define REST API on Open API (#22783)
(cherry picked from commit ba20e02)
1 parent 697ee29 commit 7ca884b

File tree

9 files changed

+99
-45
lines changed

9 files changed

+99
-45
lines changed

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

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@
3939
import javax.ws.rs.core.MediaType;
4040
import javax.ws.rs.core.StreamingOutput;
4141
import org.apache.pulsar.broker.admin.AdminResource;
42-
import org.apache.pulsar.client.api.Message;
4342
import org.apache.pulsar.common.functions.FunctionConfig;
4443
import org.apache.pulsar.common.functions.FunctionDefinition;
4544
import org.apache.pulsar.common.functions.FunctionState;
@@ -486,7 +485,7 @@ public List<String> listFunctions(
486485
@POST
487486
@ApiOperation(
488487
value = "Triggers a Pulsar Function with a user-specified value or file data",
489-
response = Message.class
488+
response = String.class
490489
)
491490
@ApiResponses(value = {
492491
@ApiResponse(code = 400, message = "Invalid request"),
@@ -541,6 +540,7 @@ public FunctionState getFunctionState(
541540
value = "Put the state associated with a Pulsar Function"
542541
)
543542
@ApiResponses(value = {
543+
@ApiResponse(code = 200, message = "Operation successful"),
544544
@ApiResponse(code = 400, message = "Invalid request"),
545545
@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
546546
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
@@ -557,8 +557,9 @@ public void putFunctionState(final @PathParam("tenant") String tenant,
557557
}
558558

559559
@POST
560-
@ApiOperation(value = "Restart an instance of a Pulsar Function", response = Void.class)
560+
@ApiOperation(value = "Restart an instance of a Pulsar Function")
561561
@ApiResponses(value = {
562+
@ApiResponse(code = 200, message = "Operation successful"),
562563
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of this function"),
563564
@ApiResponse(code = 400, message = "Invalid request"),
564565
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
@@ -578,8 +579,9 @@ public void restartFunction(
578579
}
579580

580581
@POST
581-
@ApiOperation(value = "Restart all instances of a Pulsar Function", response = Void.class)
582+
@ApiOperation(value = "Restart all instances of a Pulsar Function")
582583
@ApiResponses(value = {
584+
@ApiResponse(code = 200, message = "Operation successful"),
583585
@ApiResponse(code = 400, message = "Invalid request"),
584586
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
585587
@ApiResponse(code = 500, message = "Internal server error")
@@ -597,8 +599,9 @@ public void restartFunction(
597599
}
598600

599601
@POST
600-
@ApiOperation(value = "Stop an instance of a Pulsar Function", response = Void.class)
602+
@ApiOperation(value = "Stop an instance of a Pulsar Function")
601603
@ApiResponses(value = {
604+
@ApiResponse(code = 200, message = "Operation successful"),
602605
@ApiResponse(code = 400, message = "Invalid request"),
603606
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
604607
@ApiResponse(code = 500, message = "Internal server error")
@@ -617,8 +620,9 @@ public void stopFunction(
617620
}
618621

619622
@POST
620-
@ApiOperation(value = "Stop all instances of a Pulsar Function", response = Void.class)
623+
@ApiOperation(value = "Stop all instances of a Pulsar Function")
621624
@ApiResponses(value = {
625+
@ApiResponse(code = 200, message = "Operation successful"),
622626
@ApiResponse(code = 400, message = "Invalid request"),
623627
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
624628
@ApiResponse(code = 500, message = "Internal server error")
@@ -636,8 +640,9 @@ public void stopFunction(
636640
}
637641

638642
@POST
639-
@ApiOperation(value = "Start an instance of a Pulsar Function", response = Void.class)
643+
@ApiOperation(value = "Start an instance of a Pulsar Function")
640644
@ApiResponses(value = {
645+
@ApiResponse(code = 200, message = "Operation successful"),
641646
@ApiResponse(code = 400, message = "Invalid request"),
642647
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
643648
@ApiResponse(code = 500, message = "Internal server error")
@@ -656,8 +661,9 @@ public void startFunction(
656661
}
657662

658663
@POST
659-
@ApiOperation(value = "Start all instances of a Pulsar Function", response = Void.class)
664+
@ApiOperation(value = "Start all instances of a Pulsar Function")
660665
@ApiResponses(value = {
666+
@ApiResponse(code = 200, message = "Operation successful"),
661667
@ApiResponse(code = 400, message = "Invalid request"),
662668
@ApiResponse(code = 404, message = "The Pulsar Function does not exist"),
663669
@ApiResponse(code = 500, message = "Internal server error")
@@ -718,7 +724,8 @@ public StreamingOutput downloadFunction(
718724
@GET
719725
@ApiOperation(
720726
value = "Fetches a list of supported Pulsar IO connectors currently running in cluster mode",
721-
response = List.class
727+
response = ConnectorDefinition.class,
728+
responseContainer = "List"
722729
)
723730
@ApiResponses(value = {
724731
@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
@@ -739,6 +746,7 @@ public List<ConnectorDefinition> getConnectorsList() throws IOException {
739746
value = "Reload the built-in Functions"
740747
)
741748
@ApiResponses(value = {
749+
@ApiResponse(code = 200, message = "Operation successful"),
742750
@ApiResponse(code = 401, message = "This operation requires super-user access"),
743751
@ApiResponse(code = 503, message = "Function worker service is now initializing. Please try again later."),
744752
@ApiResponse(code = 500, message = "Internal server error")
@@ -768,6 +776,7 @@ public List<FunctionDefinition> getBuiltinFunction() {
768776
@PUT
769777
@ApiOperation(value = "Updates a Pulsar Function on the worker leader", hidden = true)
770778
@ApiResponses(value = {
779+
@ApiResponse(code = 200, message = "Operation successful"),
771780
@ApiResponse(code = 403, message = "The requester doesn't have super-user permissions"),
772781
@ApiResponse(code = 404, message = "The function does not exist"),
773782
@ApiResponse(code = 400, message = "Invalid request"),

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

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -389,8 +389,9 @@ public List<String> listSinks(@ApiParam(value = "The tenant of a Pulsar Sink")
389389
}
390390

391391
@POST
392-
@ApiOperation(value = "Restart an instance of a Pulsar Sink", response = Void.class)
392+
@ApiOperation(value = "Restart an instance of a Pulsar Sink")
393393
@ApiResponses(value = {
394+
@ApiResponse(code = 200, message = "Operation successful"),
394395
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of this sink"),
395396
@ApiResponse(code = 400, message = "Invalid restart request"),
396397
@ApiResponse(code = 401, message = "The client is not authorized to perform this operation"),
@@ -415,8 +416,9 @@ public void restartSink(@ApiParam(value = "The tenant of a Pulsar Sink")
415416
}
416417

417418
@POST
418-
@ApiOperation(value = "Restart all instances of a Pulsar Sink", response = Void.class)
419+
@ApiOperation(value = "Restart all instances of a Pulsar Sink")
419420
@ApiResponses(value = {
421+
@ApiResponse(code = 200, message = "Operation successful"),
420422
@ApiResponse(code = 400, message = "Invalid restart request"),
421423
@ApiResponse(code = 401, message = "The client is not authorized to perform this operation"),
422424
@ApiResponse(code = 404, message = "The Pulsar Sink does not exist"),
@@ -436,8 +438,9 @@ public void restartSink(@ApiParam(value = "The tenant of a Pulsar Sink")
436438
}
437439

438440
@POST
439-
@ApiOperation(value = "Stop an instance of a Pulsar Sink", response = Void.class)
441+
@ApiOperation(value = "Stop an instance of a Pulsar Sink")
440442
@ApiResponses(value = {
443+
@ApiResponse(code = 200, message = "Operation successful"),
441444
@ApiResponse(code = 400, message = "Invalid stop request"),
442445
@ApiResponse(code = 404, message = "The Pulsar Sink instance does not exist"),
443446
@ApiResponse(code = 500, message =
@@ -460,8 +463,9 @@ public void stopSink(@ApiParam(value = "The tenant of a Pulsar Sink")
460463
}
461464

462465
@POST
463-
@ApiOperation(value = "Stop all instances of a Pulsar Sink", response = Void.class)
466+
@ApiOperation(value = "Stop all instances of a Pulsar Sink")
464467
@ApiResponses(value = {
468+
@ApiResponse(code = 200, message = "Operation successful"),
465469
@ApiResponse(code = 400, message = "Invalid stop request"),
466470
@ApiResponse(code = 404, message = "The Pulsar Sink does not exist"),
467471
@ApiResponse(code = 500, message =
@@ -481,8 +485,9 @@ public void stopSink(@ApiParam(value = "The tenant of a Pulsar Sink")
481485
}
482486

483487
@POST
484-
@ApiOperation(value = "Start an instance of a Pulsar Sink", response = Void.class)
488+
@ApiOperation(value = "Start an instance of a Pulsar Sink")
485489
@ApiResponses(value = {
490+
@ApiResponse(code = 200, message = "Operation successful"),
486491
@ApiResponse(code = 400, message = "Invalid start request"),
487492
@ApiResponse(code = 404, message = "The Pulsar Sink does not exist"),
488493
@ApiResponse(code = 500, message =
@@ -505,8 +510,9 @@ public void startSink(@ApiParam(value = "The tenant of a Pulsar Sink")
505510
}
506511

507512
@POST
508-
@ApiOperation(value = "Start all instances of a Pulsar Sink", response = Void.class)
513+
@ApiOperation(value = "Start all instances of a Pulsar Sink")
509514
@ApiResponses(value = {
515+
@ApiResponse(code = 200, message = "Operation successful"),
510516
@ApiResponse(code = 400, message = "Invalid start request"),
511517
@ApiResponse(code = 404, message = "The Pulsar Sink does not exist"),
512518
@ApiResponse(code = 500, message =

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

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -323,7 +323,7 @@ public SourceStatus getSourceStatus(
323323
@ApiOperation(
324324
value = "Lists all Pulsar Sources currently deployed in a given namespace",
325325
response = String.class,
326-
responseContainer = "Collection"
326+
responseContainer = "List"
327327
)
328328
@ApiResponses(value = {
329329
@ApiResponse(code = 400, message = "Invalid request"),
@@ -342,8 +342,9 @@ public List<String> listSources(
342342
}
343343

344344
@POST
345-
@ApiOperation(value = "Restart an instance of a Pulsar Source", response = Void.class)
345+
@ApiOperation(value = "Restart an instance of a Pulsar Source")
346346
@ApiResponses(value = {
347+
@ApiResponse(code = 200, message = "Operation successful"),
347348
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace of this source"),
348349
@ApiResponse(code = 400, message = "Invalid request"),
349350
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
@@ -365,8 +366,9 @@ public void restartSource(
365366
}
366367

367368
@POST
368-
@ApiOperation(value = "Restart all instances of a Pulsar Source", response = Void.class)
369+
@ApiOperation(value = "Restart all instances of a Pulsar Source")
369370
@ApiResponses(value = {
371+
@ApiResponse(code = 200, message = "Operation successful"),
370372
@ApiResponse(code = 400, message = "Invalid request"),
371373
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
372374
@ApiResponse(code = 404, message = "Not Found(The Pulsar Source doesn't exist)"),
@@ -386,8 +388,9 @@ public void restartSource(
386388
}
387389

388390
@POST
389-
@ApiOperation(value = "Stop instance of a Pulsar Source", response = Void.class)
391+
@ApiOperation(value = "Stop instance of a Pulsar Source")
390392
@ApiResponses(value = {
393+
@ApiResponse(code = 200, message = "Operation successful"),
391394
@ApiResponse(code = 400, message = "Invalid request"),
392395
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
393396
@ApiResponse(code = 404, message = "Not Found(The Pulsar Source doesn't exist)"),
@@ -407,8 +410,9 @@ public void stopSource(
407410
}
408411

409412
@POST
410-
@ApiOperation(value = "Stop all instances of a Pulsar Source", response = Void.class)
413+
@ApiOperation(value = "Stop all instances of a Pulsar Source")
411414
@ApiResponses(value = {
415+
@ApiResponse(code = 200, message = "Operation successful"),
412416
@ApiResponse(code = 400, message = "Invalid request"),
413417
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
414418
@ApiResponse(code = 404, message = "Not Found(The Pulsar Source doesn't exist)"),
@@ -428,8 +432,9 @@ public void stopSource(
428432
}
429433

430434
@POST
431-
@ApiOperation(value = "Start an instance of a Pulsar Source", response = Void.class)
435+
@ApiOperation(value = "Start an instance of a Pulsar Source")
432436
@ApiResponses(value = {
437+
@ApiResponse(code = 200, message = "Operation successful"),
433438
@ApiResponse(code = 400, message = "Invalid request"),
434439
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
435440
@ApiResponse(code = 404, message = "Not Found(The Pulsar Source doesn't exist)"),
@@ -449,8 +454,9 @@ public void startSource(
449454
}
450455

451456
@POST
452-
@ApiOperation(value = "Start all instances of a Pulsar Source", response = Void.class)
457+
@ApiOperation(value = "Start all instances of a Pulsar Source")
453458
@ApiResponses(value = {
459+
@ApiResponse(code = 200, message = "Operation successful"),
454460
@ApiResponse(code = 400, message = "Invalid request"),
455461
@ApiResponse(code = 401, message = "Client is not authorized to perform operation"),
456462
@ApiResponse(code = 404, message = "Not Found(The Pulsar Source doesn't exist)"),

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

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,9 @@ public void getTenantAdmin(@Suspended final AsyncResponse asyncResponse,
103103
@PUT
104104
@Path("/{tenant}")
105105
@ApiOperation(value = "Create a new tenant.", notes = "This operation requires Pulsar super-user privileges.")
106-
@ApiResponses(value = {@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
106+
@ApiResponses(value = {
107+
@ApiResponse(code = 204, message = "Operation successful"),
108+
@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
107109
@ApiResponse(code = 409, message = "Tenant already exists"),
108110
@ApiResponse(code = 412, message = "Tenant name is not valid"),
109111
@ApiResponse(code = 412, message = "Clusters can not be empty"),
@@ -155,7 +157,9 @@ public void createTenant(@Suspended final AsyncResponse asyncResponse,
155157
@Path("/{tenant}")
156158
@ApiOperation(value = "Update the admins for a tenant.",
157159
notes = "This operation requires Pulsar super-user privileges.")
158-
@ApiResponses(value = {@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
160+
@ApiResponses(value = {
161+
@ApiResponse(code = 204, message = "Operation successful"),
162+
@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
159163
@ApiResponse(code = 404, message = "Tenant does not exist"),
160164
@ApiResponse(code = 409, message = "Tenant already exists"),
161165
@ApiResponse(code = 412, message = "Clusters can not be empty"),
@@ -190,7 +194,9 @@ public void updateTenant(@Suspended final AsyncResponse asyncResponse,
190194
@DELETE
191195
@Path("/{tenant}")
192196
@ApiOperation(value = "Delete a tenant and all namespaces and topics under it.")
193-
@ApiResponses(value = {@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
197+
@ApiResponses(value = {
198+
@ApiResponse(code = 204, message = "Operation successful"),
199+
@ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
194200
@ApiResponse(code = 404, message = "Tenant does not exist"),
195201
@ApiResponse(code = 405, message = "Broker doesn't allow forced deletion of tenants"),
196202
@ApiResponse(code = 409, message = "The tenant still has active namespaces")})

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,9 @@ public ResourceGroup getResourceGroup(@PathParam("resourcegroup") String resourc
6060
@PUT
6161
@Path("/{resourcegroup}")
6262
@ApiOperation(value = "Creates a new resourcegroup with the specified rate limiters")
63-
@ApiResponses(value = {@ApiResponse(code = 403, message = "Don't have admin permission"),
63+
@ApiResponses(value = {
64+
@ApiResponse(code = 204, message = "Operation successful"),
65+
@ApiResponse(code = 403, message = "Don't have admin permission"),
6466
@ApiResponse(code = 404, message = "cluster doesn't exist")})
6567
public void createOrUpdateResourceGroup(@PathParam("resourcegroup") String name,
6668
@ApiParam(value = "Rate limiters for the resourcegroup")
@@ -72,6 +74,7 @@ public void createOrUpdateResourceGroup(@PathParam("resourcegroup") String name,
7274
@Path("/{resourcegroup}")
7375
@ApiOperation(value = "Delete a resourcegroup.")
7476
@ApiResponses(value = {
77+
@ApiResponse(code = 204, message = "Operation successful"),
7578
@ApiResponse(code = 403, message = "Don't have admin permission"),
7679
@ApiResponse(code = 404, message = "ResourceGroup doesn't exist"),
7780
@ApiResponse(code = 409, message = "ResourceGroup is in use")})

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ public void setDefaultResourceQuota(
7575

7676
@GET
7777
@Path("/{tenant}/{namespace}/{bundle}")
78-
@ApiOperation(value = "Get resource quota of a namespace bundle.")
78+
@ApiOperation(value = "Get resource quota of a namespace bundle.", response = ResourceQuota.class)
7979
@ApiResponses(value = {
8080
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace"),
8181
@ApiResponse(code = 403, message = "Don't have admin permission"),
@@ -103,6 +103,7 @@ public void getNamespaceBundleResourceQuota(
103103
@Path("/{tenant}/{namespace}/{bundle}")
104104
@ApiOperation(value = "Set resource quota on a namespace.")
105105
@ApiResponses(value = {
106+
@ApiResponse(code = 204, message = "Operation successful"),
106107
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace"),
107108
@ApiResponse(code = 403, message = "Don't have admin permission"),
108109
@ApiResponse(code = 409, message = "Concurrent modification") })
@@ -133,6 +134,7 @@ public void setNamespaceBundleResourceQuota(
133134
@Path("/{tenant}/{namespace}/{bundle}")
134135
@ApiOperation(value = "Remove resource quota for a namespace.")
135136
@ApiResponses(value = {
137+
@ApiResponse(code = 204, message = "Operation successful"),
136138
@ApiResponse(code = 307, message = "Current broker doesn't serve the namespace"),
137139
@ApiResponse(code = 403, message = "Don't have admin permission"),
138140
@ApiResponse(code = 409, message = "Concurrent modification") })

0 commit comments

Comments
 (0)