You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by si...@apache.org on 2019/06/11 02:08:18 UTC
[pulsar] branch master updated: [rest] improve clusters rest
endpoint by documenting the endpoints with more swagger annotations (#4374)
This is an automated email from the ASF dual-hosted git repository.
sijie 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 d3b177f [rest] improve clusters rest endpoint by documenting the endpoints with more swagger annotations (#4374)
d3b177f is described below
commit d3b177fce849598e6346187ae91ead08305f81f0
Author: Sijie Guo <gu...@gmail.com>
AuthorDate: Tue Jun 11 10:08:11 2019 +0800
[rest] improve clusters rest endpoint by documenting the endpoints with more swagger annotations (#4374)
Co-Authored-By: Jennifer Huang <47...@users.noreply.github.com>
Co-Authored-By: Anonymitaet <50...@users.noreply.github.com>
---
.../pulsar/broker/admin/impl/ClustersBase.java | 466 +++++++++++++++++----
pulsar-client-admin-shaded/pom.xml | 5 +
pulsar-client-shaded/pom.xml | 5 +
pulsar-common/pom.xml | 13 +-
.../policies/data/AutoFailoverPolicyData.java | 26 ++
.../policies/data/AutoFailoverPolicyType.java | 6 +
.../data/BrokerNamespaceIsolationData.java | 15 +
.../pulsar/common/policies/data/ClusterData.java | 30 ++
.../pulsar/common/policies/data/FailureDomain.java | 11 +
.../policies/data/NamespaceIsolationData.java | 29 ++
pulsar-functions/runtime-all/pom.xml | 4 +
11 files changed, 519 insertions(+), 91 deletions(-)
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 867d2f5..79107b8 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
@@ -27,9 +27,12 @@ import com.google.common.collect.Lists;
import com.google.common.collect.Maps;
import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
+import io.swagger.annotations.Example;
+import io.swagger.annotations.ExampleProperty;
import java.io.IOException;
import java.util.Collections;
import java.util.LinkedHashSet;
@@ -45,6 +48,7 @@ import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
+import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response.Status;
import org.apache.bookkeeper.util.ZkUtils;
@@ -70,8 +74,14 @@ import org.slf4j.LoggerFactory;
public class ClustersBase extends AdminResource {
@GET
- @ApiOperation(value = "Get the list of all the Pulsar clusters.", response = String.class, responseContainer = "Set")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission") })
+ @ApiOperation(
+ value = "Get the list of all the Pulsar clusters.",
+ response = String.class,
+ responseContainer = "Set")
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Return a list of clusters."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
public Set<String> getClusters() throws Exception {
try {
Set<String> clusters = clustersListCache().get();
@@ -87,10 +97,24 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}")
- @ApiOperation(value = "Get the configuration data for the specified cluster.", response = ClusterData.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public ClusterData getCluster(@PathParam("cluster") String cluster) {
+ @ApiOperation(
+ value = "Get the configuration for the specified cluster.",
+ response = ClusterData.class,
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 200, message = "Return the cluster data.", response = ClusterData.class),
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public ClusterData getCluster(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster
+ ) {
validateSuperUserAccess();
try {
@@ -108,12 +132,39 @@ public class ClustersBase extends AdminResource {
@PUT
@Path("/{cluster}")
- @ApiOperation(value = "Provisions a new cluster. This operation requires Pulsar super-user privileges.", notes = "The name cannot contain '/' characters.")
- @ApiResponses(value = { @ApiResponse(code = 204, message = "Cluster has been created"),
- @ApiResponse(code = 403, message = "You don't have admin permission to create the cluster"),
- @ApiResponse(code = 409, message = "Cluster already exists"),
- @ApiResponse(code = 412, message = "Cluster name is not valid") })
- public void createCluster(@PathParam("cluster") String cluster, ClusterData clusterData) {
+ @ApiOperation(
+ value = "Create a new cluster.",
+ 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 = 403, message = "You don't have admin permission to create the cluster."),
+ @ApiResponse(code = 409, message = "Cluster already exists."),
+ @ApiResponse(code = 412, message = "Cluster name is not valid."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void createCluster(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The cluster data",
+ required = true,
+ examples = @Example(
+ value = @ExampleProperty(
+ mediaType = MediaType.APPLICATION_JSON,
+ value =
+ "{\n"
+ + " 'serviceUrl': 'http://pulsar.example.com:8080',\n"
+ + " 'brokerServiceUrl': 'pulsar://pulsar.example.com:6651',\n"
+ + "}"
+ )
+ )
+ )
+ ClusterData clusterData
+ ) {
validateSuperUserAccess();
validatePoliciesReadOnlyAccess();
@@ -135,11 +186,37 @@ public class ClustersBase extends AdminResource {
@POST
@Path("/{cluster}")
- @ApiOperation(value = "Update the configuration for a cluster.", notes = "This operation requires Pulsar super-user privileges.")
- @ApiResponses(value = { @ApiResponse(code = 204, message = "Cluster has been updated"),
- @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public void updateCluster(@PathParam("cluster") String cluster, ClusterData clusterData) {
+ @ApiOperation(
+ 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 = 403, message = "Don't have admin permission or policies are read-only."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void updateCluster(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The cluster data",
+ required = true,
+ examples = @Example(
+ value = @ExampleProperty(
+ mediaType = MediaType.APPLICATION_JSON,
+ value =
+ "{\n"
+ + " 'serviceUrl': 'http://pulsar.example.com:8080',\n"
+ + " 'brokerServiceUrl': 'pulsar://pulsar.example.com:6651'\n"
+ + "}"
+ )
+ )
+ )
+ ClusterData clusterData
+ ) {
validateSuperUserAccess();
validatePoliciesReadOnlyAccess();
@@ -171,12 +248,38 @@ public class ClustersBase extends AdminResource {
@POST
@Path("/{cluster}/peers")
- @ApiOperation(value = "Update peer-cluster-list for a cluster.", notes = "This operation requires Pulsar super-user privileges.")
- @ApiResponses(value = { @ApiResponse(code = 204, message = "Cluster has been updated"),
- @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 412, message = "Peer cluster doesn't exist"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public void setPeerClusterNames(@PathParam("cluster") String cluster, LinkedHashSet<String> peerClusterNames) {
+ @ApiOperation(
+ value = "Update peer-cluster-list for a cluster.",
+ notes = "This operation requires Pulsar superuser privileges.")
+ @ApiResponses(value = {
+ @ApiResponse(code = 204, message = "Cluster has been updated."),
+ @ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 412, message = "Peer cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void setPeerClusterNames(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The list of peer cluster names",
+ required = true,
+ examples = @Example(
+ value = @ExampleProperty(
+ mediaType = MediaType.APPLICATION_JSON,
+ value =
+ "[\n"
+ + " 'cluster-a',\n"
+ + " 'cluster-b'\n"
+ + "]"
+ )
+ )
+ )
+ LinkedHashSet<String> peerClusterNames
+ ) {
validateSuperUserAccess();
validatePoliciesReadOnlyAccess();
@@ -224,10 +327,24 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/peers")
- @ApiOperation(value = "Get the peer-cluster data for the specified cluster.", response = Set.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public Set<String> getPeerCluster(@PathParam("cluster") String cluster) {
+ @ApiOperation(
+ value = "Get the peer-cluster data for the specified cluster.",
+ response = String.class,
+ responseContainer = "Set",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public Set<String> getPeerCluster(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster
+ ) {
validateSuperUserAccess();
try {
@@ -246,12 +363,24 @@ public class ClustersBase extends AdminResource {
@DELETE
@Path("/{cluster}")
- @ApiOperation(value = "Delete an existing cluster")
- @ApiResponses(value = { @ApiResponse(code = 204, message = "Cluster has been updated"),
- @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist"),
- @ApiResponse(code = 412, message = "Cluster is not empty") })
- public void deleteCluster(@PathParam("cluster") String cluster) {
+ @ApiOperation(
+ value = "Delete an existing cluster.",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 204, message = "Cluster has been deleted."),
+ @ApiResponse(code = 403, message = "Don't have admin permission or policies are read-only."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 412, message = "Cluster is not empty."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void deleteCluster(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster
+ ) {
validateSuperUserAccess();
validatePoliciesReadOnlyAccess();
@@ -329,11 +458,24 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/namespaceIsolationPolicies")
- @ApiOperation(value = "Get the namespace isolation policies assigned in the cluster", response = NamespaceIsolationData.class, responseContainer = "Map")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public Map<String, NamespaceIsolationData> getNamespaceIsolationPolicies(@PathParam("cluster") String cluster)
- throws Exception {
+ @ApiOperation(
+ value = "Get the namespace isolation policies assigned to the cluster.",
+ response = NamespaceIsolationData.class,
+ responseContainer = "Map",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public Map<String, NamespaceIsolationData> getNamespaceIsolationPolicies(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster
+ ) throws Exception {
validateSuperUserAccess();
if (!clustersCache().get(path("clusters", cluster)).isPresent()) {
throw new RestException(Status.NOT_FOUND, "Cluster " + cluster + " does not exist.");
@@ -354,12 +496,29 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/namespaceIsolationPolicies/{policyName}")
- @ApiOperation(value = "Get a single namespace isolation policy assigned in the cluster", response = NamespaceIsolationData.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Policy doesn't exist"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public NamespaceIsolationData getNamespaceIsolationPolicy(@PathParam("cluster") String cluster,
- @PathParam("policyName") String policyName) throws Exception {
+ @ApiOperation(
+ value = "Get the single namespace isolation policy assigned to the cluster.",
+ response = NamespaceIsolationData.class,
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Policy doesn't exist."),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public NamespaceIsolationData getNamespaceIsolationPolicy(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The name of the namespace isolation policy",
+ required = true
+ )
+ @PathParam("policyName") String policyName
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
@@ -385,11 +544,23 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/namespaceIsolationPolicies/brokers")
- @ApiOperation(value = "Get list of brokers with namespace-isolation policies attached to them", response = BrokerNamespaceIsolationData.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Namespace-isolation policies not found"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
+ @ApiOperation(
+ value = "Get list of brokers with namespace-isolation policies attached to them.",
+ response = BrokerNamespaceIsolationData.class,
+ responseContainer = "set",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Namespace-isolation policies not found."),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
public List<BrokerNamespaceIsolationData> getBrokersWithNamespaceIsolationPolicy(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
@PathParam("cluster") String cluster) {
validateSuperUserAccess();
validateClusterExists(cluster);
@@ -434,12 +605,29 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/namespaceIsolationPolicies/brokers/{broker}")
- @ApiOperation(value = "Get a broker with namespace-isolation policies attached to it", response = BrokerNamespaceIsolationData.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Namespace-isolation policies/ Broker not found"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public BrokerNamespaceIsolationData getBrokerWithNamespaceIsolationPolicy(@PathParam("cluster") String cluster,
- @PathParam("broker") String broker) {
+ @ApiOperation(
+ value = "Get a broker with namespace-isolation policies attached to it.",
+ response = BrokerNamespaceIsolationData.class,
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission."),
+ @ApiResponse(code = 404, message = "Namespace-isolation policies/ Broker not found."),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public BrokerNamespaceIsolationData getBrokerWithNamespaceIsolationPolicy(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The broker name (<broker-hostname>:<web-service-port>)",
+ required = true,
+ example = "broker1:8080"
+ )
+ @PathParam("broker") String broker) {
validateSuperUserAccess();
validateClusterExists(cluster);
@@ -484,11 +672,34 @@ public class ClustersBase extends AdminResource {
@POST
@Path("/{cluster}/namespaceIsolationPolicies/{policyName}")
- @ApiOperation(value = "Set namespace isolation policy")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission or plicy is read only"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public void setNamespaceIsolationPolicy(@PathParam("cluster") String cluster,
- @PathParam("policyName") String policyName, NamespaceIsolationData policyData) throws Exception {
+ @ApiOperation(
+ value = "Set namespace isolation policy.",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @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."),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void setNamespaceIsolationPolicy(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The namespace isolation policy name",
+ required = true
+ )
+ @PathParam("policyName") String policyName,
+ @ApiParam(
+ value = "The namespace isolation policy data",
+ required = true
+ )
+ NamespaceIsolationData policyData
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
validatePoliciesReadOnlyAccess();
@@ -555,11 +766,28 @@ public class ClustersBase extends AdminResource {
@DELETE
@Path("/{cluster}/namespaceIsolationPolicies/{policyName}")
- @ApiOperation(value = "Delete namespace isolation policy")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission or plicy is read only"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public void deleteNamespaceIsolationPolicy(@PathParam("cluster") String cluster,
- @PathParam("policyName") String policyName) throws Exception {
+ @ApiOperation(
+ value = "Delete namespace isolation policy.",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @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."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void deleteNamespaceIsolationPolicy(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The namespace isolation policy name",
+ required = true
+ )
+ @PathParam("policyName") String policyName
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
validatePoliciesReadOnlyAccess();
@@ -596,12 +824,34 @@ public class ClustersBase extends AdminResource {
@POST
@Path("/{cluster}/failureDomains/{domainName}")
- @ApiOperation(value = "Set cluster's failure Domain")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 409, message = "Broker already exists in another domain"),
- @ApiResponse(code = 404, message = "Cluster doesn't exist") })
- public void setFailureDomain(@PathParam("cluster") String cluster, @PathParam("domainName") String domainName,
- FailureDomain domain) throws Exception {
+ @ApiOperation(
+ value = "Set the failure domain of the cluster.",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @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."),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist."),
+ @ApiResponse(code = 500, message = "Internal server error.")
+ })
+ public void setFailureDomain(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The failure domain name",
+ required = true
+ )
+ @PathParam("domainName") String domainName,
+ @ApiParam(
+ value = "The configuration data of a failure domain",
+ required = true
+ )
+ FailureDomain domain
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
validateBrokerExistsInOtherDomain(cluster, domainName, domain);
@@ -629,9 +879,23 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/failureDomains")
- @ApiOperation(value = "Get the cluster failure domains", response = FailureDomain.class, responseContainer = "Map")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission") })
- public Map<String, FailureDomain> getFailureDomains(@PathParam("cluster") String cluster) throws Exception {
+ @ApiOperation(
+ value = "Get the cluster failure domains.",
+ response = FailureDomain.class,
+ responseContainer = "Map",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission"),
+ @ApiResponse(code = 500, message = "Internal server error")
+ })
+ public Map<String, FailureDomain> getFailureDomains(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster
+ ) throws Exception {
validateSuperUserAccess();
Map<String, FailureDomain> domains = Maps.newHashMap();
@@ -660,12 +924,29 @@ public class ClustersBase extends AdminResource {
@GET
@Path("/{cluster}/failureDomains/{domainName}")
- @ApiOperation(value = "Get a domain in a cluster", response = FailureDomain.class)
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission"),
- @ApiResponse(code = 404, message = "Domain doesn't exist"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public FailureDomain getDomain(@PathParam("cluster") String cluster, @PathParam("domainName") String domainName)
- throws Exception {
+ @ApiOperation(
+ value = "Get a domain in a cluster",
+ response = FailureDomain.class,
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @ApiResponse(code = 403, message = "Don't have admin permission"),
+ @ApiResponse(code = 404, message = "FailureDomain doesn't exist"),
+ @ApiResponse(code = 412, message = "Cluster doesn't exist"),
+ @ApiResponse(code = 500, message = "Internal server error")
+ })
+ public FailureDomain getDomain(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The failure domain name",
+ required = true
+ )
+ @PathParam("domainName") String domainName
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
@@ -684,11 +965,28 @@ public class ClustersBase extends AdminResource {
@DELETE
@Path("/{cluster}/failureDomains/{domainName}")
- @ApiOperation(value = "Delete cluster's failure omain")
- @ApiResponses(value = { @ApiResponse(code = 403, message = "Don't have admin permission or plicy is read only"),
- @ApiResponse(code = 412, message = "Cluster doesn't exist") })
- public void deleteFailureDomain(@PathParam("cluster") String cluster, @PathParam("domainName") String domainName)
- throws Exception {
+ @ApiOperation(
+ value = "Delete the failure domain of the cluster",
+ notes = "This operation requires Pulsar superuser privileges."
+ )
+ @ApiResponses(value = {
+ @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"),
+ @ApiResponse(code = 500, message = "Internal server error")
+ })
+ public void deleteFailureDomain(
+ @ApiParam(
+ value = "The cluster name",
+ required = true
+ )
+ @PathParam("cluster") String cluster,
+ @ApiParam(
+ value = "The failure domain name",
+ required = true
+ )
+ @PathParam("domainName") String domainName
+ ) throws Exception {
validateSuperUserAccess();
validateClusterExists(cluster);
diff --git a/pulsar-client-admin-shaded/pom.xml b/pulsar-client-admin-shaded/pom.xml
index d72feac..31178c9 100644
--- a/pulsar-client-admin-shaded/pom.xml
+++ b/pulsar-client-admin-shaded/pom.xml
@@ -95,6 +95,7 @@
<include>io.opencensus:*</include>
<include>org.objenesis:*</include>
<include>org.yaml:snakeyaml</include>
+ <include>io.swagger:*</include>
<include>org.apache.bookkeeper:bookkeeper-common-allocator</include>
</includes>
</artifactSet>
@@ -221,6 +222,10 @@
<shadedPattern>org.apache.pulsar.shade.org.yaml</shadedPattern>
</relocation>
<relocation>
+ <pattern>io.swagger</pattern>
+ <shadedPattern>org.apache.pulsar.shade.io.swagger</shadedPattern>
+ </relocation>
+ <relocation>
<pattern>org.apache.bookkeeper</pattern>
<shadedPattern>org.apache.pulsar.shade.org.apache.bookkeeper</shadedPattern>
</relocation>
diff --git a/pulsar-client-shaded/pom.xml b/pulsar-client-shaded/pom.xml
index 543c601..ebeb4e9 100644
--- a/pulsar-client-shaded/pom.xml
+++ b/pulsar-client-shaded/pom.xml
@@ -114,6 +114,7 @@
<include>org.eclipse.jetty:*</include>
<include>com.yahoo.datasketches:*</include>
<include>commons-*:*</include>
+ <include>io.swagger:*</include>
<include>org.apache.pulsar:pulsar-common</include>
<include>org.apache.bookkeeper:circe-checksum</include>
@@ -174,6 +175,10 @@
<shadedPattern>org.apache.pulsar.shade.io.netty</shadedPattern>
</relocation>
<relocation>
+ <pattern>io.swagger</pattern>
+ <shadedPattern>org.apache.pulsar.shade.io.swagger</shadedPattern>
+ </relocation>
+ <relocation>
<pattern>org.apache.pulsar.policies</pattern>
<shadedPattern>org.apache.pulsar.shade.org.apache.pulsar.policies</shadedPattern>
</relocation>
diff --git a/pulsar-common/pom.xml b/pulsar-common/pom.xml
index 419dcf4..9b40e00 100644
--- a/pulsar-common/pom.xml
+++ b/pulsar-common/pom.xml
@@ -40,8 +40,12 @@
<artifactId>pulsar-client-api</artifactId>
<version>${project.version}</version>
</dependency>
-
-
+
+ <dependency>
+ <groupId>io.swagger</groupId>
+ <artifactId>swagger-annotations</artifactId>
+ </dependency>
+
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
@@ -135,11 +139,6 @@
<artifactId>jackson-dataformat-yaml</artifactId>
</dependency>
- <dependency>
- <groupId>io.swagger</groupId>
- <artifactId>swagger-annotations</artifactId>
- </dependency>
-
</dependencies>
<build>
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java
index 50ad45f..3963bc9 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java
@@ -20,14 +20,40 @@ package org.apache.pulsar.common.policies.data;
import static com.google.common.base.Preconditions.checkArgument;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.util.Map;
import org.apache.pulsar.common.policies.impl.AutoFailoverPolicyFactory;
import com.google.common.base.Objects;
+@ApiModel(
+ value = "AutoFailoverPolicyData",
+ description = "The auto failover policy configuration data"
+)
public class AutoFailoverPolicyData {
+ @ApiModelProperty(
+ name = "policy_type",
+ value = "The auto failover policy type",
+ allowableValues = "min_available"
+ )
public AutoFailoverPolicyType policy_type;
+ @ApiModelProperty(
+ name = "parameters",
+ value =
+ "The parameters applied to the auto failover policy specified by `policy_type`.\n"
+ + "The parameters for 'min_available' are :\n"
+ + " - 'min_limit': the limit of minimal number of available brokers in primary"
+ + " group before auto failover\n"
+ + " - 'usage_threshold': the resource usage threshold. If the usage of a broker"
+ + " is beyond this value, it would be marked as unavailable\n",
+ example =
+ "{\n"
+ + " \"min_limit\": 3,\n"
+ + " \"usage_threshold\": 80\n"
+ + "}\n"
+ )
public Map<String, String> parameters;
@Override
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyType.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyType.java
index 569942d..c457f0d 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyType.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyType.java
@@ -18,6 +18,12 @@
*/
package org.apache.pulsar.common.policies.data;
+import io.swagger.annotations.ApiModel;
+
+@ApiModel(
+ value = "AutoFailoverPolicyType",
+ description = "The policy type of auto failover."
+)
public enum AutoFailoverPolicyType {
min_available
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/BrokerNamespaceIsolationData.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/BrokerNamespaceIsolationData.java
index 65f3bdd..e20fbe9 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/BrokerNamespaceIsolationData.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/BrokerNamespaceIsolationData.java
@@ -18,13 +18,28 @@
*/
package org.apache.pulsar.common.policies.data;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.util.List;
import com.google.common.base.Objects;
+@ApiModel(
+ value = "BrokerNamespaceIsolationData",
+ description = "The namespace isolation data for a given broker"
+)
public class BrokerNamespaceIsolationData {
+ @ApiModelProperty(
+ name = "brokerName",
+ value = "The broker name",
+ example = "broker1:8080"
+ )
public String brokerName;
+ @ApiModelProperty(
+ name = "namespaceRegex",
+ value = "The namespace-isolation policies attached to this broker"
+ )
public List<String> namespaceRegex; //isolated namespace regex
@Override
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/ClusterData.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/ClusterData.java
index a383bc6..538ed48 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/ClusterData.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/ClusterData.java
@@ -20,18 +20,48 @@ package org.apache.pulsar.common.policies.data;
import static com.google.common.base.Preconditions.checkNotNull;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.util.LinkedHashSet;
import java.util.Objects;
import com.google.common.base.MoreObjects;
+@ApiModel(
+ value = "ClusterData",
+ description = "The configuration data for a cluster"
+)
public class ClusterData {
+ @ApiModelProperty(
+ name = "serviceUrl",
+ value = "The HTTP rest service URL (for admin operations)",
+ example = "http://pulsar.example.com:8080"
+ )
private String serviceUrl;
+ @ApiModelProperty(
+ name = "serviceUrlTls",
+ value = "The HTTPS rest service URL (for admin operations)",
+ example = "https://pulsar.example.com:8443"
+ )
private String serviceUrlTls;
+ @ApiModelProperty(
+ name = "brokerServiceUrl",
+ value = "The broker service url (for produce and consume operations)",
+ example = "pulsar://pulsar.example.com:6650"
+ )
private String brokerServiceUrl;
+ @ApiModelProperty(
+ name = "brokerServiceUrlTls",
+ value = "The secured broker service url (for produce and consume operations)",
+ example = "pulsar+ssl://pulsar.example.com:6651"
+ )
private String brokerServiceUrlTls;
// For given Cluster1(us-west1, us-east1) and Cluster2(us-west2, us-east2)
// Peer: [us-west1 -> us-west2] and [us-east1 -> us-east2]
+ @ApiModelProperty(
+ name = "peerClusterNames",
+ value = "A set of peer cluster names"
+ )
private LinkedHashSet<String> peerClusterNames;
public ClusterData() {
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/FailureDomain.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/FailureDomain.java
index d27cd06..cf0ef4c 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/FailureDomain.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/FailureDomain.java
@@ -20,11 +20,22 @@ package org.apache.pulsar.common.policies.data;
import com.google.common.base.MoreObjects;
import com.google.common.base.Objects;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.util.HashSet;
import java.util.Set;
+@ApiModel(
+ value = "FailureDomain",
+ description = "The data of a failure domain configuration in a cluster"
+)
public class FailureDomain {
+ @ApiModelProperty(
+ name = "brokers",
+ value = "The collection of brokers in the same failure domain",
+ example = "[ 'broker-1', 'broker-2' ]"
+ )
public Set<String> brokers = new HashSet<String>();
public Set<String> getBrokers() {
diff --git a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java
index 8088bcb..4aa03b5 100644
--- a/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java
+++ b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java
@@ -20,16 +20,45 @@ package org.apache.pulsar.common.policies.data;
import static com.google.common.base.Preconditions.checkArgument;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
import java.util.ArrayList;
import java.util.List;
import com.google.common.base.Objects;
+@ApiModel(
+ value = "NamespaceIsolationData",
+ description = "The data of namespace isolation configuration"
+)
public class NamespaceIsolationData {
+ @ApiModelProperty(
+ name = "namespaces",
+ value = "The list of namespaces to apply this namespace isolation data"
+ )
public List<String> namespaces = new ArrayList<String>();
+ @ApiModelProperty(
+ name = "primary",
+ value = "The list of primary brokers for serving the list of namespaces in this isolation policy"
+ )
public List<String> primary = new ArrayList<String>();
+ @ApiModelProperty(
+ name = "primary",
+ value = "The list of secondary brokers for serving the list of namespaces in this isolation policy"
+ )
public List<String> secondary = new ArrayList<String>();
+ @ApiModelProperty(
+ name = "auto_failover_policy",
+ value = "The data of auto-failover policy configuration",
+ example =
+ "{"
+ + " \"policy_type\": \"min_available\""
+ + " \"parameters\": {"
+ + " \"\": \"\""
+ + " }"
+ + "}"
+ )
public AutoFailoverPolicyData auto_failover_policy;
@Override
diff --git a/pulsar-functions/runtime-all/pom.xml b/pulsar-functions/runtime-all/pom.xml
index d479027..1933332 100644
--- a/pulsar-functions/runtime-all/pom.xml
+++ b/pulsar-functions/runtime-all/pom.xml
@@ -396,6 +396,10 @@
<shadedPattern>org.apache.pulsar.functions.runtime.shaded.org.apache.logging</shadedPattern>
</relocation>
-->
+ <relocation>
+ <pattern>io.swagger</pattern>
+ <shadedPattern>org.apache.pulsar.functions.runtime.shaded.io.swagger</shadedPattern>
+ </relocation>
</relocations>
</configuration>
</execution>