[rest] improve clusters rest endpoint by documenting the endpoints wi…

…th more swagger annotations (apache#4374) Co-Authored-By: Jennifer Huang <[email protected]> Co-Authored-By: Anonymitaet <[email protected]>
zxw7606 · Jun 11, 2019 · d3b177f · d3b177f
1 parent 6c71908
commit d3b177f
Show file tree

Hide file tree

Showing 11 changed files with 519 additions and 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
diff --git 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>
@@ -220,6 +221,10 @@
                       <pattern>org.yaml</pattern>
                       <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>

diff --git 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>
@@ -173,6 +174,10 @@
                   <pattern>io.netty</pattern>
                   <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>

diff --git 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/...r-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java b/...r-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyData.java
@@ -20,14 +20,40 @@
 
 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/...r-common/src/main/java/org/apache/pulsar/common/policies/data/AutoFailoverPolicyType.java b/...r-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/...on/src/main/java/org/apache/pulsar/common/policies/data/BrokerNamespaceIsolationData.java b/...on/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
@@ -20,18 +20,48 @@
 
 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
@@ -20,11 +20,22 @@
 
 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/...r-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java b/...r-common/src/main/java/org/apache/pulsar/common/policies/data/NamespaceIsolationData.java
@@ -20,16 +20,45 @@
 
 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
@@ -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>