[website] Render Pulsar REST API in ReDoc and Fix endpoint template (#…

…2274) * Update swagger version * [website] Render Pulsar REST API in ReDoc and Fix endpoint template ### Motivation [ReDoc](https://github.com/Rebilly/ReDoc) provides a good mechanism to load OpenAPI/Swagger-generated API reference documentation. ### Changes - Use ReDoc to load the pulsar swagger definition - Fix the rest admin api references and `endpoint` macros * Address comments
apache · Aug 1, 2018 · 6b77a23 · 6b77a23
1 parent b0b3cee
commit 6b77a23
Show file tree

Hide file tree

Showing 33 changed files with 2,461 additions and 7,049 deletions.
diff --git a/pom.xml b/pom.xml
@@ -612,13 +612,13 @@ flexible messaging model and an intuitive client API.</description>
       <dependency>
         <groupId>io.swagger</groupId>
         <artifactId>swagger-core</artifactId>
-        <version>1.5.3</version>
+        <version>1.5.20</version>
       </dependency>
 
       <dependency>
-        <groupId>com.wordnik</groupId>
+        <groupId>io.swagger</groupId>
         <artifactId>swagger-annotations</artifactId>
-        <version>1.5.3-M1</version>
+        <version>1.5.20</version>
       </dependency>
 
       <dependency>

diff --git a/pulsar-broker-shaded/pom.xml b/pulsar-broker-shaded/pom.xml
@@ -103,7 +103,6 @@
                   <include>com.github.zafarkhaja:java-semver</include>
                   <include>org.aspectj:*</include>
                   <include>com.ea.agentloader:*</include>
-                  <include>com.wordnik:swagger-annotations</include>
                   <include>org.apache.httpcomponents:httpclient</include>
                   <include>commons-logging:commons-logging</include>
                   <include>org.apache.httpcomponents:httpcore</include>

diff --git a/pulsar-broker/pom.xml b/pulsar-broker/pom.xml
@@ -206,7 +206,7 @@
     </dependency>
 
     <dependency>
-      <groupId>com.wordnik</groupId>
+      <groupId>io.swagger</groupId>
       <artifactId>swagger-annotations</artifactId>
     </dependency>
 
@@ -361,12 +361,11 @@
                   <springmvc>false</springmvc>
                   <locations>org.apache.pulsar.broker.admin</locations>
                   <schemes>http,https</schemes>
-                  <basePath>/admin</basePath>
+                  <basePath>/admin/v2</basePath>
                   <info>
                     <title>Pulsar Admin REST API</title>
-                    <version>v1</version>
-                    <description>This provides the REST API for admin
-                      operations</description>
+                    <version>v2</version>
+                    <description>This provides the REST API for admin operations</description>
                     <license>
                       <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
                       <name>Apache 2.0</name>

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/BrokerStats.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/BrokerStats.java
@@ -24,7 +24,6 @@
 import io.swagger.annotations.ApiResponses;
 import org.apache.pulsar.broker.admin.impl.BrokerStatsBase;
 import org.apache.pulsar.broker.loadbalance.ResourceUnit;
-import org.apache.pulsar.common.naming.NamespaceName;
 
 import javax.ws.rs.GET;
 import javax.ws.rs.Path;
@@ -35,7 +34,7 @@
 import java.util.Map;
 
 @Path("/broker-stats")
-@Api(value = "/broker-stats", description = "Stats for broker", tags = "broker-stats")
+@Api(value = "/broker-stats", description = "Stats for broker", tags = "broker-stats", hidden = true)
 @Produces(MediaType.APPLICATION_JSON)
 public class BrokerStats extends BrokerStatsBase {
 

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Brokers.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Brokers.java
@@ -26,7 +26,7 @@
 import javax.ws.rs.core.MediaType;
 
 @Path("/brokers")
-@Api(value = "/brokers", description = "BrokersBase admin apis", tags = "brokers")
+@Api(value = "/brokers", description = "BrokersBase admin apis", tags = "brokers", hidden = true)
 @Produces(MediaType.APPLICATION_JSON)
 public class Brokers extends BrokersBase {
 }
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Clusters.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Clusters.java
@@ -26,7 +26,7 @@
 import javax.ws.rs.core.MediaType;
 
 @Path("/clusters")
-@Api(value = "/clusters", description = "Cluster admin apis", tags = "clusters")
+@Api(value = "/clusters", description = "Cluster admin apis", tags = "clusters", hidden = true)
 @Produces(MediaType.APPLICATION_JSON)
 public class Clusters extends ClustersBase {
 }
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Functions.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Functions.java
@@ -23,6 +23,6 @@
 import org.apache.pulsar.broker.admin.impl.FunctionsBase;
 
 @Path("/functions")
-@Api(value = "/functions", description = "Functions admin apis", tags = "functions")
+@Api(value = "/functions", description = "Functions admin apis", tags = "functions", hidden = true)
 public class Functions extends FunctionsBase {
 }
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java
@@ -18,13 +18,10 @@
  */
 package org.apache.pulsar.broker.admin.v1;
 
-import static org.apache.commons.lang3.StringUtils.isBlank;
 import static org.apache.pulsar.broker.cache.ConfigurationCacheService.POLICIES;
-import static org.apache.pulsar.broker.cache.ConfigurationCacheService.POLICIES_ROOT;
 
 import java.util.List;
 import java.util.Map;
-import java.util.Optional;
 import java.util.Set;
 
 import javax.ws.rs.Consumes;
@@ -40,10 +37,8 @@
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response.Status;
 
-import org.apache.pulsar.broker.admin.AdminResource;
 import org.apache.pulsar.broker.admin.impl.NamespacesBase;
 import org.apache.pulsar.broker.web.RestException;
-import org.apache.pulsar.common.naming.NamespaceName;
 import org.apache.pulsar.common.policies.data.AuthAction;
 import org.apache.pulsar.common.policies.data.BacklogQuota;
 import org.apache.pulsar.common.policies.data.BacklogQuota.BacklogQuotaType;
@@ -54,7 +49,6 @@
 import org.apache.pulsar.common.policies.data.RetentionPolicies;
 import org.apache.pulsar.common.policies.data.SubscriptionAuthMode;
 import org.apache.zookeeper.KeeperException;
-import org.apache.zookeeper.data.Stat;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -68,7 +62,7 @@
 @Path("/namespaces")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
-@Api(value = "/namespaces", description = "Namespaces admin apis", tags = "namespaces")
+@Api(value = "/namespaces", description = "Namespaces admin apis", tags = "namespaces", hidden = true)
 @SuppressWarnings("deprecation")
 public class Namespaces extends NamespacesBase {
 

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java
@@ -41,7 +41,6 @@
 import javax.ws.rs.core.Response.Status;
 
 import org.apache.pulsar.broker.PulsarServerException;
-import org.apache.pulsar.broker.service.BrokerService;
 import org.apache.pulsar.broker.service.Topic;
 import org.apache.pulsar.broker.service.nonpersistent.NonPersistentTopic;
 import org.apache.pulsar.broker.web.RestException;
@@ -62,7 +61,7 @@
  */
 @Path("/non-persistent")
 @Produces(MediaType.APPLICATION_JSON)
-@Api(value = "/non-persistent", description = "Non-Persistent topic admin apis", tags = "non-persistent topic")
+@Api(value = "/non-persistent", description = "Non-Persistent topic admin apis", tags = "non-persistent topic", hidden = true)
 @SuppressWarnings("deprecation")
 public class NonPersistentTopics extends PersistentTopics {
     private static final Logger log = LoggerFactory.getLogger(NonPersistentTopics.class);

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java
@@ -58,7 +58,7 @@
  */
 @Path("/persistent")
 @Produces(MediaType.APPLICATION_JSON)
-@Api(value = "/persistent", description = "Persistent topic admin apis", tags = "persistent topic")
+@Api(value = "/persistent", description = "Persistent topic admin apis", tags = "persistent topic", hidden = true)
 @SuppressWarnings("deprecation")
 public class PersistentTopics extends PersistentTopicsBase {
 

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Properties.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Properties.java
@@ -29,6 +29,6 @@
 @Path("/properties")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
-@Api(value = "/properties", description = "TenantsBase admin apis", tags = "properties")
+@Api(value = "/properties", description = "TenantsBase admin apis", tags = "properties", hidden = true)
 public class Properties extends TenantsBase {
 }
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/ResourceQuotas.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/ResourceQuotas.java
@@ -38,7 +38,7 @@
 @Path("/resource-quotas")
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
-@Api(value = "/resource-quotas", description = "Quota admin APIs", tags = "resource-quotas")
+@Api(value = "/resource-quotas", description = "Quota admin APIs", tags = "resource-quotas", hidden = true)
 public class ResourceQuotas extends ResourceQuotasBase {
 
     @GET

diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Functions.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v2/Functions.java
@@ -18,8 +18,7 @@
  */
 package org.apache.pulsar.broker.admin.v2;
 
-import com.wordnik.swagger.annotations.Api;
-
+import io.swagger.annotations.Api;
 import javax.ws.rs.Consumes;
 import javax.ws.rs.Path;
 import javax.ws.rs.Produces;
@@ -28,7 +27,7 @@
 import org.apache.pulsar.broker.admin.impl.FunctionsBase;
 
 @Path("/functions")
-@Api(value = "/functions", description = "Functions admin apis", tags = "functions")
+@Api(value = "/functions", description = "Functions admin apis", tags = "functions", hidden = true)
 @Produces(MediaType.APPLICATION_JSON)
 @Consumes(MediaType.APPLICATION_JSON)
 public class Functions extends FunctionsBase {

diff --git a/pulsar-discovery-service/pom.xml b/pulsar-discovery-service/pom.xml
@@ -123,7 +123,7 @@
     </dependency>
 
     <dependency>
-      <groupId>com.wordnik</groupId>
+      <groupId>io.swagger</groupId>
       <artifactId>swagger-annotations</artifactId>
     </dependency>
 

diff --git a/site2/docs/admin-api-brokers.md b/site2/docs/admin-api-brokers.md
@@ -6,13 +6,13 @@ sidebar_label: Brokers
 
 Pulsar brokers consist of two components:
 
-1. An HTTP server exposing a [REST interface](reference-rest-api.md) administration and [topic](reference-terminology.md#topic) lookup.
+1. An HTTP server exposing a {@inject: rest:REST:/} interface administration and [topic](reference-terminology.md#topic) lookup.
 2. A dispatcher that handles all Pulsar [message](reference-terminology.md#message) transfers.
 
 [Brokers](reference-terminology.md#broker) can be managed via:
 
 * The [`brokers`](reference-pulsar-admin.md#brokers) command of the [`pulsar-admin`](reference-pulsar-admin.md) tool
-* The `/admin/v2/brokers` endpoint of the admin [REST API](reference-rest-api.md)
+* The `/admin/v2/brokers` endpoint of the admin {@inject: rest:REST:/} API
 * The `brokers` method of the {@inject: javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin.html} object in the [Java API](client-libraries-java.md)
 
 In addition to being configurable when you start them up, brokers can also be [dynamically configured](#dynamic-broker-configuration).
@@ -38,9 +38,7 @@ broker1.use.org.com:8080
 
 ###### REST
 
-{% endpoint GET /admin/v2/brokers/:cluster %}
-
-[More info](reference-rest-api.md#/admin/brokers/:cluster)
+{@inject: endpoint|GET|/admin/v2/brokers/:cluster|operation/getActiveBrokers}
 
 ###### Java
 
@@ -70,7 +68,7 @@ $ pulsar-admin brokers namespaces use \
 ```
 ###### REST
 
-{% endpoint GET /admin/v2/brokers/:cluster/:broker:/ownedNamespaces %}
+{@inject: endpoint|GET|/admin/v2/brokers/:cluster/:broker/ownedNamespaces|operation/getOwnedNamespaes}
 
 ###### Java
 
@@ -85,7 +83,7 @@ One way to configure a Pulsar [broker](reference-terminology.md#broker) is to su
 But since all broker configuration in Pulsar is stored in ZooKeeper, configuration values can also be dynamically updated *while the broker is running*. When you update broker configuration dynamically, ZooKeeper will notify the broker of the change and the broker will then override any existing configuration values.
 
 * The [`brokers`](reference-pulsar-admin.md#brokers) command for the [`pulsar-admin`](reference-pulsar-admin.md) tool has a variety of subcommands that enable you to manipulate a broker's configuration dynamically, enabling you to [update config values](#update-dynamic-configuration) and more.
-* In the Pulsar admin [REST API](reference-rest-api.md), dynamic configuration is managed through the `/admin/v2/brokers/configuration` endpoint.
+* In the Pulsar admin {@inject: rest:REST:/} API, dynamic configuration is managed through the `/admin/v2/brokers/configuration` endpoint.
 
 ### Update dynamic configuration
 
@@ -99,9 +97,7 @@ $ pulsar-admin brokers update-dynamic-config brokerShutdownTimeoutMs 100
 
 #### REST API
 
-{% endpoint POST /admin/v2/brokers/configuration/:configName/:configValue %}
-
-[More info](reference-rest-api.md#/admin/brokers/configuration/:configName/:configValue)
+{@inject: endpoint|POST|/admin/v2/brokers/configuration/:configName/:configValue|operation/updateDynamicConfiguration}
 
 #### Java
 
@@ -122,9 +118,7 @@ brokerShutdownTimeoutMs
 
 #### REST API
 
-{% endpoint GET /admin/v2/brokers/configuration %}
-
-[More info](reference-rest-api.md#/admin/brokers/configuration)
+{@inject: endpoint|GET|/admin/v2/brokers/configuration|operation/getDynamicConfigurationName}
 
 #### Java
 
@@ -145,9 +139,7 @@ brokerShutdownTimeoutMs:100
 
 #### REST API
 
-{% endpoint GET /admin/v2/brokers/configuration/values %}
-
-[More info](reference-rest-api.md#/admin/brokers/configuration/values)
+{@inject: endpoint|GET|/admin/v2/brokers/configuration/values|operation/getAllDynamicConfigurations}
 
 #### Java
 

diff --git a/site2/docs/admin-api-clusters.md b/site2/docs/admin-api-clusters.md
@@ -10,7 +10,7 @@ servers (aka [bookies](reference-terminology.md#bookie)), and a [ZooKeeper](http
 Clusters can be managed via:
 
 * The [`clusters`](reference-pulsar-admin.md#clusters) command of the [`pulsar-admin`](reference-pulsar-admin.md) tool
-* The `/admin/v2/clusters` endpoint of the admin [REST API](reference-rest-api.md)
+* The `/admin/v2/clusters` endpoint of the admin {@inject: rest:REST:/} API
 * The `clusters` method of the {@inject: javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object in the [Java API](client-libraries-java.md)
 
 ## Clusters resources
@@ -33,9 +33,7 @@ $ pulsar-admin clusters create cluster-1 \
 
 #### REST API
 
-{% endpoint PUT /admin/v2/clusters/:cluster %}
-
-[More info](reference-rest-api.md#/admin/clusters/:cluster)
+{@inject: endpoint|PUT|/admin/v2/clusters/:cluster|operation/createCluster}
 
 #### Java
 
@@ -104,9 +102,7 @@ $ pulsar-admin clusters get cluster-1
 
 #### REST API
 
-{% endpoint GET /admin/v2/clusters/:cluster %}
-
-[More info](reference-rest-api.md#/admin/clusters/:cluster)
+{@inject: endpoint|GET|/admin/v2/clusters/:cluster|operation/getCluster}
 
 #### Java
 
@@ -130,9 +126,7 @@ $ pulsar-admin clusters update cluster-1 \
 
 #### REST
 
-{% endpoint POST /admin/v2/clusters/:cluster %}
-
-[More info](reference-rest-api.md#/admin/clusters/:cluster)
+{@inject: endpoint|POST|/admin/v2/clusters/:cluster|operation/updateCluster}
 
 #### Java
 
@@ -160,9 +154,7 @@ $ pulsar-admin clusters delete cluster-1
 
 #### REST API
 
-{% endpoint DELETE /admin/v2/clusters/:cluster %}
-
-[More info](reference-rest-api.md#/admin/clusters/:cluster)
+{@inject: endpoint|DELETE|/admin/v2/clusters/:cluster|operation/deleteCluster}
 
 #### Java
 
@@ -186,9 +178,7 @@ cluster-2
 
 #### REST API
 
-{% endpoint GET /admin/v2/clusters %}
-
-[More info](reference-rest-api.md#/admin/clusters)
+{@inject: endpoint|GET|/admin/v2/clusters|operation/getClusters}
 
 ###### Java
 
@@ -210,9 +200,7 @@ $ pulsar-admin update-peer-clusters cluster-1 --peer-clusters cluster-2
 
 #### REST API
 
-{% endpoint POST /admin/v2/clusters/:cluster/peers %}
-
-[More info](reference-rest-api.md#/admin/clusters/:cluster/peers)
+{@inject: endpoint|POST|/admin/v2/clusters/:cluster/peers|operation/setPeerClusterNames}
 
 #### Java