From 6b77a23564a805096b0f9b6a2f7153ac8b0c3ec3 Mon Sep 17 00:00:00 2001 From: Sijie Guo Date: Wed, 1 Aug 2018 01:19:37 -0700 Subject: [PATCH] [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 --- pom.xml | 6 +- pulsar-broker-shaded/pom.xml | 1 - pulsar-broker/pom.xml | 9 +- .../pulsar/broker/admin/v1/BrokerStats.java | 3 +- .../pulsar/broker/admin/v1/Brokers.java | 2 +- .../pulsar/broker/admin/v1/Clusters.java | 2 +- .../pulsar/broker/admin/v1/Functions.java | 2 +- .../pulsar/broker/admin/v1/Namespaces.java | 8 +- .../broker/admin/v1/NonPersistentTopics.java | 3 +- .../broker/admin/v1/PersistentTopics.java | 2 +- .../pulsar/broker/admin/v1/Properties.java | 2 +- .../broker/admin/v1/ResourceQuotas.java | 2 +- .../pulsar/broker/admin/v2/Functions.java | 5 +- pulsar-discovery-service/pom.xml | 2 +- site2/docs/admin-api-brokers.md | 24 +- site2/docs/admin-api-clusters.md | 26 +- site2/docs/admin-api-namespaces.md | 20 +- site2/docs/admin-api-non-persistent-topics.md | 25 +- site2/docs/admin-api-overview.md | 6 +- site2/docs/admin-api-partitioned-topics.md | 42 +- site2/docs/admin-api-persistent-topics.md | 120 +- site2/docs/administration-geo.md | 2 +- site2/docs/administration-zk-bk.md | 12 +- site2/docs/cookbooks-compaction.md | 2 +- site2/docs/cookbooks-retention-expiry.md | 49 +- ...tting-started-concepts-and-architecture.md | 4 +- site2/docs/reference-rest-api.md | 8 - site2/website/package.json | 5 +- site2/website/pages/en/admin-rest-api.js | 26 +- site2/website/sidebars.json | 2 +- site2/website/siteConfig.js | 19 + site2/website/static/swagger/swagger.json | 9038 +++++------------ src/gen-swagger.sh | 31 + 33 files changed, 2461 insertions(+), 7049 deletions(-) delete mode 100644 site2/docs/reference-rest-api.md create mode 100755 src/gen-swagger.sh diff --git a/pom.xml b/pom.xml index c0e23b4bd3eaa..30aedf603f726 100644 --- a/pom.xml +++ b/pom.xml @@ -612,13 +612,13 @@ flexible messaging model and an intuitive client API. io.swagger swagger-core - 1.5.3 + 1.5.20 - com.wordnik + io.swagger swagger-annotations - 1.5.3-M1 + 1.5.20 diff --git a/pulsar-broker-shaded/pom.xml b/pulsar-broker-shaded/pom.xml index 1adc84f0f741e..08ce2985a5251 100644 --- a/pulsar-broker-shaded/pom.xml +++ b/pulsar-broker-shaded/pom.xml @@ -103,7 +103,6 @@ com.github.zafarkhaja:java-semver org.aspectj:* com.ea.agentloader:* - com.wordnik:swagger-annotations org.apache.httpcomponents:httpclient commons-logging:commons-logging org.apache.httpcomponents:httpcore diff --git a/pulsar-broker/pom.xml b/pulsar-broker/pom.xml index ac264bdf5bf6b..296799ce0e283 100644 --- a/pulsar-broker/pom.xml +++ b/pulsar-broker/pom.xml @@ -206,7 +206,7 @@ - com.wordnik + io.swagger swagger-annotations @@ -361,12 +361,11 @@ false org.apache.pulsar.broker.admin http,https - /admin + /admin/v2 Pulsar Admin REST API - v1 - This provides the REST API for admin - operations + v2 + This provides the REST API for admin operations http://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0 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 index 76aea674bbf6c..1b3e028f35051 100644 --- 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 index 3b7af349925a8..79f31ddd87222 100644 --- 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 index 7cd5ccd454017..6aaee8fdd15c9 100644 --- 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 index 17407321991aa..7eca553b246e1 100644 --- 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 index bbc44386261c1..6b607ab3e2a92 100644 --- 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 index f73a82992695b..f6d8640fd823a 100644 --- 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 index 1ebb79a901a57..b5fd76cc86aea 100644 --- 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 index 20a20b010a2fa..b8a6b643c5cb5 100644 --- 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 index fb77ee0336a75..6fcf14eb57075 100644 --- 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 index b91e53327ec7e..854a365aaab37 100644 --- 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 index 259f0a9aa1e3c..d8387409b7802 100644 --- a/pulsar-discovery-service/pom.xml +++ b/pulsar-discovery-service/pom.xml @@ -123,7 +123,7 @@ - com.wordnik + io.swagger swagger-annotations diff --git a/site2/docs/admin-api-brokers.md b/site2/docs/admin-api-brokers.md index 3d7ea5cbd8165..99daad1515023 100644 --- 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 index eb873efd38b1c..d593a9386f152 100644 --- 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 diff --git a/site2/docs/admin-api-namespaces.md b/site2/docs/admin-api-namespaces.md index a203c83317c99..52ba7ab6dc50b 100644 --- a/site2/docs/admin-api-namespaces.md +++ b/site2/docs/admin-api-namespaces.md @@ -9,7 +9,7 @@ Pulsar [namespaces](reference-terminology.md#namespace) are logical groupings of Namespaces can be managed via: * The [`namespaces`](reference-pulsar-admin.md#clusters) command of the [`pulsar-admin`](reference-pulsar-admin.md) tool -* The `/admin/v2/namespaces` endpoint of the admin [REST API](reference-rest-api.md) +* The `/admin/v2/namespaces` endpoint of the admin {@inject: rest:REST:/} API * The `namespaces` method of the {@inject: javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object in the [Java API](client-libraries-java.md) ## Namespaces resources @@ -28,9 +28,7 @@ $ pulsar-admin namespaces create test-tenant/test-namespace #### REST API -{% endpoint PUT /admin/v2/namespaces/:tenant/:namespace %} - -[More info](reference-rest-api.md#/admin/namespaces/:tenant/:namespace) +{@inject: endpoint|PUT|/admin/v2/namespaces/:tenant/:namespace|operation/createNamespace} #### Java @@ -73,9 +71,7 @@ $ pulsar-admin namespaces policies test-tenant/test-namespace #### REST API -{% endpoint GET /admin/v2/namespaces/:tenant/:namespace %} - -[More info](reference-rest-api.md#/admin/namespaces/:tenant/:namespace) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace|operation/getPolicies} #### Java @@ -99,9 +95,7 @@ test-tenant/ns2 #### REST API -{% endpoint GET /admin/v2/namespaces/:tenant %} - -[More info](reference-rest-api.md#/admin/namespaces/:tenant) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant|operation/getTenantNamespaces} #### Java @@ -130,9 +124,7 @@ $ pulsar-admin namespaces delete test-tenant/ns1 #### REST -{% endpoint DELETE /admin/v2/namespaces/:tenant/:namespace %} - -[More info](reference-rest-api.md#/admin/namespaces/:tenant/:namespace) +{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace|operation/deleteNamespace} #### Java @@ -155,7 +147,7 @@ $ pulsar-admin namespaces set-clusters test-tenant/ns1 \ ###### REST ``` -{% endpoint POST /admin/v2/namespaces/:tenant/:namespace/replication %} +{@inject: endpoint POST|/admin/v2/namespaces/:tenant/:namespace/replication|operation/setNamespaceReplicationClusters} ``` ###### Java diff --git a/site2/docs/admin-api-non-persistent-topics.md b/site2/docs/admin-api-non-persistent-topics.md index 4a4d7efab4c8a..bf3fdd130b9c6 100644 --- a/site2/docs/admin-api-non-persistent-topics.md +++ b/site2/docs/admin-api-non-persistent-topics.md @@ -124,14 +124,14 @@ $ pulsar-admin non-persistent stats \ #### REST API -{% endpoint GET /admin/v2/non-persistent/:tenant/:namespace/:destination/stats %} +{@inject: endpoint|GET|/admin/v2/non-persistent/:tenant/:namespace/:topic/stats|operation/getStats} #### Java ```java -String destination = "non-persistent://my-tenant/my-namespace/my-topic"; -admin.nonPersistentTopics().getStats(destination); +String topic = "non-persistent://my-tenant/my-namespace/my-topic"; +admin.nonPersistentTopics().getStats(topic); ``` ### Get internal stats @@ -165,14 +165,13 @@ $ pulsar-admin non-persistent stats-internal \ #### REST API -{% endpoint GET /admin/v2/non-persistent/:tenant/:namespace/:destination/internalStats %} - +{@inject: endpoint|GET|/admin/v2/non-persistent/:tenant/:namespace/:topic/internalStats|operation/getInternalStats} #### Java ```java -String destination = "non-persistent://my-tenant/my-namespace/my-topic"; -admin.nonPersistentTopics().getInternalStats(destination); +String topic = "non-persistent://my-tenant/my-namespace/my-topic"; +admin.nonPersistentTopics().getInternalStats(topic); ``` ### Create partitioned topic @@ -189,7 +188,7 @@ $ bin/pulsar-admin non-persistent create-partitioned-topic \ #### REST API -{% endpoint PUT /admin/v2/non-persistent/:tenant/:namespace/:destination/partitions %} +{@inject: endpoint|PUT|/admin/v2/non-persistent/:tenant/:namespace/:topic/partitions|operation/createPartitionedTopic} #### Java @@ -219,7 +218,7 @@ $ pulsar-admin non-persistent get-partitioned-topic-metadata \ #### REST API -{% endpoint GET /admin/v2/non-persistent/:tenant/:namespace/:destination/partitions %} +{@inject: endpoint|GET|/admin/v2/non-persistent/:tenant/:namespace/:topic/partitions|operation/getPartitionedMetadata} #### Java @@ -244,13 +243,11 @@ $ pulsar-admin non-persistent unload \ #### REST API -{% endpoint PUT /admin/v2/non-persistent/:tenant/:namespace/:destination/unload %} - -[More info](reference-rest-api.md#/admin/non-persistent/:tenant/:namespace/:destination/unload) +{@inject: endpoint|PUT|/admin/v2/non-persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic} #### Java ```java -String destination = "non-persistent://my-tenantmy-namespace/my-topic"; -admin.nonPersistentTopics().unload(destination); +String topic = "non-persistent://my-tenantmy-namespace/my-topic"; +admin.nonPersistentTopics().unload(topic); ``` diff --git a/site2/docs/admin-api-overview.md b/site2/docs/admin-api-overview.md index db77a8db3f665..7b48c864ed848 100644 --- a/site2/docs/admin-api-overview.md +++ b/site2/docs/admin-api-overview.md @@ -8,7 +8,7 @@ The Pulsar admin interface enables you to manage all of the important entities i You can currently interact with the admin interface via: -- Making HTTP calls against the admin [REST API](reference-rest-api.md) provided by Pulsar [brokers](reference-terminology.md#broker). For some restful apis, they might be redirected to topic owner brokers for serving +- Making HTTP calls against the admin {@inject: rest:REST:/} API provided by Pulsar [brokers](reference-terminology.md#broker). For some restful apis, they might be redirected to topic owner brokers for serving with [`307 Temporary Redirect`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307), hence the HTTP callers should handle `307 Temporary Redirect`. If you are using `curl`, you should specify `-L` to handle redirections. - The `pulsar-admin` CLI tool, which is available in the `bin` folder of your [Pulsar installation](getting-started-standalone.md): @@ -28,7 +28,7 @@ In this document, examples from each of the three available interfaces will be s ## Admin setup -Each of Pulsar's three admin interfaces---the [`pulsar-admin`](reference-pulsar-admin.md) CLI tool, the [Java admin API](/api/admin), and the [REST API](reference-rest-api.md)---requires some special setup if you have [authentication](security-overview.md#authentication-providers) enabled in your Pulsar [instance](reference-terminology.md#instance). +Each of Pulsar's three admin interfaces---the [`pulsar-admin`](reference-pulsar-admin.md) CLI tool, the [Java admin API](/api/admin), and the {@inject: rest:REST:/} API ---requires some special setup if you have [authentication](security-overview.md#authentication-providers) enabled in your Pulsar [instance](reference-terminology.md#instance). ### pulsar-admin @@ -46,7 +46,7 @@ If you have [authentication](security-overview.md#authentication-providers) enab ### REST API -You can find documentation for the REST API exposed by Pulsar [brokers](reference-terminology.md#broker) in [this reference document](reference-rest-api.md). +You can find documentation for the REST API exposed by Pulsar [brokers](reference-terminology.md#broker) in this reference {@inject: rest:document:/}. ### Java admin client diff --git a/site2/docs/admin-api-partitioned-topics.md b/site2/docs/admin-api-partitioned-topics.md index 85f2d78159d9c..575b1cab688f0 100644 --- a/site2/docs/admin-api-partitioned-topics.md +++ b/site2/docs/admin-api-partitioned-topics.md @@ -34,11 +34,7 @@ $ bin/pulsar-admin topics create-partitioned-topic \ #### REST API -```http -PUT /admin/v2/persistent/:tenant/:namespace/:topic/partitions -``` - -[More info](reference-admin-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/partitions) +{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/partitions|operation/createPartitionedTopic} #### Java @@ -73,11 +69,7 @@ $ pulsar-admin topics get-partitioned-topic-metadata \ #### REST API -```http -GET /admin/v2/persistent/:tenant/:namespace/:topic/partitions %} -``` - -[More info](reference-admin-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/partitions) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/partitions|operation/getPartitionedMetadata} #### Java @@ -112,11 +104,7 @@ $ pulsar-admin topics update-partitioned-topic \ #### REST API -```http -POST /admin/v2/persistent/:tenant/:cluster/:namespace/:destination/partitions -``` - -[More info](reference-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/partitions) +{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:cluster/:namespace/:destination/partitions|operation/updatePartitionedTopic} #### Java @@ -138,11 +126,7 @@ $ bin/pulsar-admin topics delete-partitioned-topic \ #### REST API -```http -DELETE /admin/v2/persistent/:topic/:namespace/:destination/partitions -``` - -[More info](reference-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/partitions) +{@inject: endpoint|DELETE|/admin/v2/persistent/:topic/:namespace/:destination/partitions|operation/deletePartitionedTopic} #### Java @@ -164,11 +148,7 @@ persistent://tenant/namespace/topic2 #### REST API -```http -GET /admin/v2/persistent/:tenant/:namespace -``` - -[More info](reference-rest-api.md#/admin/v2/persistent/:tenant/:namespace) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getPartitionedTopicList} #### Java @@ -256,11 +236,7 @@ $ pulsar-admin topics partitioned-stats \ #### REST API -```http -GET /admin/v2/persistent/:tenant/:namespace/:topic/partitioned-stats -``` - -[More info](reference-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/partitioned-stats) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/partitioned-stats|operation/getPartitionedStats} #### Java @@ -347,11 +323,7 @@ $ pulsar-admin topics stats-internal \ #### REST API -```http -GET /admin/v2/persistent/:tenant/:namespace/:topic/internalStats -``` - -[More info](reference-rest-api.md#/admin/v2/persistent/:tenant/:namespace/:topic/internalStats) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/internalStats|operation/getInternalStats} #### Java diff --git a/site2/docs/admin-api-persistent-topics.md b/site2/docs/admin-api-persistent-topics.md index b77db1ecec0b1..ef9d18fb34e62 100644 --- a/site2/docs/admin-api-persistent-topics.md +++ b/site2/docs/admin-api-persistent-topics.md @@ -30,9 +30,7 @@ $ pulsar-admin persistent list \ #### REST API -{% endpoint GET /admin/v2/persistent/:tenant/:namespace %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getList} #### Java @@ -58,17 +56,15 @@ $ pulsar-admin persistent grant-permission \ #### REST API -{% endpoint POST /admin/v2/namespaces/:tenant/:namespace/permissions/:role %} - -[More info](../../reference/RestApi#/admin/namespaces/:tenant/:namespace/permissions/:role) +{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/grantPermissionsOnTopic} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String role = "test-role"; Set actions = Sets.newHashSet(AuthAction.produce, AuthAction.consume); -admin.persistentTopics().grantPermission(destination, role, actions); +admin.persistentTopics().grantPermission(topic, role, actions); ``` ### Get permission @@ -91,15 +87,13 @@ $ pulsar-admin persistent permissions \ #### REST API -{% endpoint GET /admin/v2/namespaces/:tenant/:namespace/permissions %} - -[More info](../../reference/RestApi#/admin/namespaces/:tenant:namespace/permissions) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/permissions|operation/getPermissionsOnTopic} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().getPermissions(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().getPermissions(topic); ``` ### Revoke permission @@ -125,16 +119,14 @@ $ pulsar-admin persistent revoke-permission \ #### REST API -{% endpoint DELETE /admin/v2/namespaces/:tenant:namespace/permissions/:role %} - -[More info](../../reference/RestApi#/admin/namespaces/:tenant/:namespace/permissions/:role) +{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String role = "test-role"; -admin.persistentTopics().revokePermissions(destination, role); +admin.persistentTopics().revokePermissions(topic, role); ``` ### Delete topic @@ -152,15 +144,13 @@ $ pulsar-admin persistent delete \ #### REST API -{% endpoint DELETE /admin/v2/persistent/:tenant/:namespace/:destination %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination) +{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().delete(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().delete(topic); ``` ### Unload topic @@ -178,15 +168,13 @@ $ pulsar-admin persistent unload \ #### REST API -{% endpoint PUT /admin/v2/persistent/:tenant/:namespace/:destination/unload %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/unload) +{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().unload(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().unload(topic); ``` ### Get stats @@ -289,15 +277,13 @@ $ pulsar-admin persistent stats \ #### REST API -{% endpoint GET /admin/v2/persistent/:tenant/:namespace/:destination/stats %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant:namespace/:destination/stats) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/stats|operation/getStats} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().getStats(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().getStats(topic); ``` ### Get internal stats @@ -399,15 +385,13 @@ $ pulsar-admin persistent stats-internal \ #### REST API -{% endpoint GET /admin/v2/persistent/:tenant/:namespace/:destination/internalStats %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/internalStats) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/internalStats|operation/getInternalStats} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().getInternalStats(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().getInternalStats(topic); ``` ### Peek messages @@ -429,17 +413,15 @@ msg-payload #### REST API -{% endpoint GET /admin/v2/persistent/:tenant/:namespace/:destination/subscription/:subName/position/:messagePosition %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/subscription/:subName/position/:messagePosition) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/subscription/:subName/position/:messagePosition|operation/peekNthMessage} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String subName = "my-subscription"; int numMessages = 1; -admin.persistentTopics().peekMessages(destination, subName, numMessages); +admin.persistentTopics().peekMessages(topic, subName, numMessages); ``` ### Skip messages @@ -457,17 +439,15 @@ $ pulsar-admin persistent skip \ #### REST API -{% endpoint POST /admin/v2/persistent/:tenant/:namespace/:destination/subscription/:subName/skip/:numMessages %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/subscription/:subName/skip/:numMessages) +{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:namespace/:topic/subscription/:subName/skip/:numMessages|operation/skipMessages} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String subName = "my-subscription"; int numMessages = 1; -admin.persistentTopics().skipMessages(destination, subName, numMessages); +admin.persistentTopics().skipMessages(topic, subName, numMessages); ``` ### Skip all messages @@ -485,16 +465,16 @@ $ pulsar-admin persistent skip-all \ #### REST API -{% endpoint POST /admin/v2/persistent/:tenant/:namespace/:destination/subscription/:subName/skip_all %} +{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:namespace/:topic/subscription/:subName/skip_all|operation/skipAllMessages} -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/subscription/:subName/skip_all) +[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:topic/subscription/:subName/skip_all) #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String subName = "my-subscription"; -admin.persistentTopics().skipAllMessages(destination, subName); +admin.persistentTopics().skipAllMessages(topic, subName); ``` ### Reset cursor @@ -512,17 +492,15 @@ $ pulsar-admin persistent reset-cursor \ #### REST API -{% endpoint POST /admin/v2/persistent/:tenant/:namespace/:destination/subscription/:subName/resetcursor/:timestamp %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/subscription/:subName/resetcursor/:timestamp) +{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:namespace/:topic/subscription/:subName/resetcursor/:timestamp|operation/resetCursor} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String subName = "my-subscription"; long timestamp = 2342343L; -admin.persistentTopics().skipAllMessages(destination, subName, timestamp); +admin.persistentTopics().skipAllMessages(topic, subName, timestamp); ``` ### Lookup of topic @@ -541,13 +519,13 @@ $ pulsar-admin persistent lookup \ #### REST API -{% endpoint GET /lookup/v2/destination/persistent/:tenant:namespace/:destination %} +{@inject: endpoint|GET|/lookup/v2/topic/persistent/:tenant:namespace/:topic|/} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.lookup().lookupDestination(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.lookup().lookupDestination(topic); ``` ### Get bundle @@ -566,13 +544,13 @@ $ pulsar-admin persistent bundle-range \ #### REST API -{% endpoint GET /lookup/v2/destination/:destination_domain/:tenant/:namespace/:destination/bundle %} +{@inject: endpoint|GET|/lookup/v2/topic/:topic_domain/:tenant/:namespace/:topic/bundle|/} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.lookup().getBundleRange(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.lookup().getBundleRange(topic); ``` @@ -591,15 +569,13 @@ $ pulsar-admin persistent subscriptions \ #### REST API -{% endpoint GET /admin/v2/persistent/:tenant/:namespace/:destination/subscriptions %} - -[More info](../../reference/RestApi#/admin/persistent/:tenant/:namespace/:destination/subscriptions) +{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/subscriptions|operation/getSubscriptions} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; -admin.persistentTopics().getSubscriptions(destination); +String topic = "persistent://my-tenant/my-namespace/my-topic"; +admin.persistentTopics().getSubscriptions(topic); ``` ### Unsubscribe @@ -617,14 +593,12 @@ $ pulsar-admin persistent unsubscribe \ #### REST API -{% endpoint POST /admin/v2/namespaces/:tenant/:namespace/unsubscribe/:subscription %} - -[More info](../../reference/RestApi#/admin/namespaces/:tenant/:namespace/unsubscribe/:subscription) +{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/:topic/subscription/:subscription|operation/deleteSubscription} #### Java ```java -String destination = "persistent://my-tenant/my-namespace/my-topic"; +String topic = "persistent://my-tenant/my-namespace/my-topic"; String subscriptionName = "my-subscription"; -admin.persistentTopics().deleteSubscription(destination, subscriptionName); +admin.persistentTopics().deleteSubscription(topic, subscriptionName); ``` diff --git a/site2/docs/administration-geo.md b/site2/docs/administration-geo.md index 4f65127a61f80..ef727c673857f 100644 --- a/site2/docs/administration-geo.md +++ b/site2/docs/administration-geo.md @@ -107,7 +107,7 @@ producer.newMessage() #### Topic stats -Topic-specific statistics for global topics are available via the [`pulsar-admin`](reference-pulsar-admin.md) tool and [REST API](reference-rest-api.md): +Topic-specific statistics for global topics are available via the [`pulsar-admin`](reference-pulsar-admin.md) tool and {@inject: rest:REST:/} API: ```shell $ bin/pulsar-admin persistent stats persistent://my-tenant/my-namespace/my-topic diff --git a/site2/docs/administration-zk-bk.md b/site2/docs/administration-zk-bk.md index 7f8c69c8d9b71..8c8f29a20ff20 100644 --- a/site2/docs/administration-zk-bk.md +++ b/site2/docs/administration-zk-bk.md @@ -268,11 +268,7 @@ $ pulsar-admin namespaces set-persistence my-tenant/my-ns \ #### REST API -```http -POST /admin/v2/namespaces/:tenant/:namespace/persistence -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/persistence) +{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/persistence|operation/setPersistence} #### Java @@ -308,11 +304,7 @@ $ pulsar-admin namespaces get-persistence my-tenant/my-ns #### REST API -```http -GET /admin/v2/namespaces/:tenant/:namespace/persistence -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/persistence) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/persistence|operation/getPersistence} #### Java diff --git a/site2/docs/cookbooks-compaction.md b/site2/docs/cookbooks-compaction.md index bf8fce8a34d1a..6b50dca1894e5 100644 --- a/site2/docs/cookbooks-compaction.md +++ b/site2/docs/cookbooks-compaction.md @@ -49,7 +49,7 @@ $ bin/pulsar-admin topics compact \ persistent://my-tenant/my-namespace/my-topic ``` -The `pulsar-admin` tool runs compaction via the Pulsar [REST API](reference-rest-api.md). To run compaction in its own dedicated process, i.e. *not* through the REST API, you can use the [`pulsar compact-topic`](reference-cli-tools.md#pulsar-compact-topic) command. Here's an example: +The `pulsar-admin` tool runs compaction via the Pulsar {@inject: rest:REST:/} API. To run compaction in its own dedicated process, i.e. *not* through the REST API, you can use the [`pulsar compact-topic`](reference-cli-tools.md#pulsar-compact-topic) command. Here's an example: ```bash $ bin/pulsar compact-topic \ diff --git a/site2/docs/cookbooks-retention-expiry.md b/site2/docs/cookbooks-retention-expiry.md index d961b25182705..cd1a96a8d064b 100644 --- a/site2/docs/cookbooks-retention-expiry.md +++ b/site2/docs/cookbooks-retention-expiry.md @@ -77,10 +77,7 @@ $ pulsar-admin namespaces set-retention my-tenant/my-ns \ #### REST API -```http -POST /admin/v2/namespaces/:tenant/:namespace/retention -``` -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/retention) +{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/retention|operation/setRetention} #### Java @@ -111,11 +108,7 @@ $ pulsar-admin namespaces get-retention my-tenant/my-ns #### REST API -```http -GET /admin/v2/namespaces/:tenant/:namespace/retention -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/retention) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/retention|operation/getRetention} #### Java @@ -165,11 +158,7 @@ $ pulsar-admin namespaces set-backlog-quota my-tenant/my-ns \ #### REST API -```http -POST /admin/v2/namespaces/:tenant/:namespace/backlogQuota -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/backlogQuota) +{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/backlogQuota|operation/getBacklogQuotaMap} #### Java @@ -200,13 +189,7 @@ $ pulsar-admin namespaces get-backlog-quotas my-tenant/my-ns #### REST API -{% endpoint GET /admin/namespaces/:property/:cluster/:namespace/backlogQuotaMap %} - -```http -GET /admin/v2/namespaces/:tenant/:namespace/backlogQuotaMap -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/backlogQuota) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/backlogQuotaMap|operation/getBacklogQuotaMap} #### Java @@ -227,12 +210,7 @@ $ pulsar-admin namespaces remove-backlog-quotas my-tenant/my-ns #### REST API -```http -DELETE /admin/v2/namespaces/:tenant/:namespace/backlogQuota -``` - - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/backlogQuota) +{@inject: endpoint|DELETE|/admin/v2/namespaces/:tenant/:namespace/backlogQuota|operation/removeBacklogQuota} #### Java @@ -273,13 +251,7 @@ $ pulsar-admin namespaces set-message-ttl my-tenant/my-ns \ #### REST API -{% endpoint POST /admin/namespaces/:property/:cluster/:namespace/messageTTL %} - -```http -POST /admin/v2/namespaces/:tenant/:namespace/messageTTL -``` - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/messageTTL) +{@inject: endpoint|POST|/admin/v2/namespaces/:tenant/:namespace/messageTTL|operation/setNamespaceMessageTTL} #### Java @@ -302,14 +274,7 @@ $ pulsar-admin namespaces get-message-ttl my-tenant/my-ns #### REST API -{% endpoint GET /admin/namespaces/:property/:cluster/:namespace/messageTTL %} - -```http -GET /admin/v2/namespaces/:tenant/:namespace/messageTTL -``` - - -[More info](reference-rest-api.md#/admin/namespaces/:property/:cluster/:namespace/messageTTL) +{@inject: endpoint|GET|/admin/v2/namespaces/:tenant/:namespace/messageTTL|operation/getNamespaceMessageTTL} #### Java diff --git a/site2/docs/getting-started-concepts-and-architecture.md b/site2/docs/getting-started-concepts-and-architecture.md index af62864eb85a3..cf6b81c626b35 100644 --- a/site2/docs/getting-started-concepts-and-architecture.md +++ b/site2/docs/getting-started-concepts-and-architecture.md @@ -289,7 +289,7 @@ At the broader instance level, an instance-wide ZooKeeper cluster called the con The Pulsar message broker is a stateless component that's primarily responsible for running two other components: -* An HTTP server that exposes a REST API for both [administrative tasks](reference-rest-api.md) and [topic lookup](#client-setup-phase) for producers and consumers +* An HTTP server that exposes a {@inject: rest:REST:/} API for both administrative tasks and [topic lookup](#client-setup-phase) for producers and consumers * A dispatcher, which is an asynchronous TCP server over a custom [binary protocol](developing-binary-protocol.md) used for all data transfers Messages are typically dispatched out of a [managed ledger](#managed-ledgers) cache for the sake of performance, *unless* the backlog exceeds the cache size. If the backlog grows too large for the cache, the broker will start reading entries from BookKeeper. @@ -649,7 +649,7 @@ Both approaches are available in Pulsar, and you're free to adopt one or the oth ### Basic architecture -In Pulsar, schemas are uploaded to, fetched from, and update via Pulsar's [REST API](reference-rest-api.md). +In Pulsar, schemas are uploaded to, fetched from, and update via Pulsar's {@inject: rest:REST:/} API. > #### Other schema registry backends > Out of the box, Pulsar uses the [Apache BookKeeper](#persistent-storage) log storage system for schema storage. You can, however, use different backends if you wish. Documentation for custom schema storage logic is coming soon. diff --git a/site2/docs/reference-rest-api.md b/site2/docs/reference-rest-api.md deleted file mode 100644 index 0c89ec4968cb3..0000000000000 --- a/site2/docs/reference-rest-api.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: reference-rest-api -title: Pulsar Admin Rest API -sidebar_label: REST API ---- - -# [Pulsar Admin REST API](/staging/admin-rest-api) - diff --git a/site2/website/package.json b/site2/website/package.json index ae5f6e0fc21c6..41acd5507a7cc 100644 --- a/site2/website/package.json +++ b/site2/website/package.json @@ -18,9 +18,12 @@ "jest-puppeteer": "^3.2.1", "puppeteer": "^1.5.0", "remarkable-embed": "^0.4.1", - "replace-in-file": "^3.4.0" + "replace-in-file": "^3.4.0", + "redoc": "^2.0.0-alpha.30" }, "jest": { "preset": "jest-puppeteer" + }, + "dependencies": { } } diff --git a/site2/website/pages/en/admin-rest-api.js b/site2/website/pages/en/admin-rest-api.js index cce71d45c0383..dd32e733a3b92 100644 --- a/site2/website/pages/en/admin-rest-api.js +++ b/site2/website/pages/en/admin-rest-api.js @@ -1,4 +1,3 @@ - const React = require('react'); const CompLibrary = require('../../core/CompLibrary.js'); @@ -9,32 +8,11 @@ class AdminRestApi extends React.Component { render() { const swaggerUrl = `${siteConfig.baseUrl}swagger/swagger.json` - const swagger = ` - const ui = SwaggerUIBundle({ - url: "${swaggerUrl}", - dom_id: '#swagger-ui', - presets: [ - SwaggerUIBundle.presets.apis - ], - filter: true, - //deepLinking: true, - //displayOperationId: true, - showCommonExtensions: true, - showExtensions: true, - //defaultModelRendering: "model", - defaultModelsExpandDepth: 0, - docExpansion: "list", - layout: "BaseLayout" - }) - ` - return (
-
- - + +