rest: add swagger doc for tenants (apache#4421)

* add swagger doc for tenants * fix lincense issue * update following matteo's comments
adamkeyser · Jun 5, 2019 · 49e51db · 49e51db
1 parent 0d16b90
commit 49e51db
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 12 deletions.
diff --git a/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/TenantsBase.java b/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/impl/TenantsBase.java
@@ -18,6 +18,7 @@
  */
 package org.apache.pulsar.broker.admin.impl;
 
+import io.swagger.annotations.ApiParam;
 import java.util.List;
 import java.util.Set;
 import java.util.stream.Collectors;
@@ -48,7 +49,7 @@
 public class TenantsBase extends AdminResource {
 
     @GET
-    @ApiOperation(value = "Get the list of tenants.", response = String.class, responseContainer = "List")
+    @ApiOperation(value = "Get the list of existing tenants.", response = String.class, responseContainer = "List")
     @ApiResponses(value = { @ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
             @ApiResponse(code = 404, message = "Tenant doesn't exist") })
     public List<String> getTenants() {
@@ -69,7 +70,9 @@ public List<String> getTenants() {
     @ApiOperation(value = "Get the admin configuration for a given tenant.")
     @ApiResponses(value = { @ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
             @ApiResponse(code = 404, message = "Tenant does not exist") })
-    public TenantInfo getTenantAdmin(@PathParam("tenant") String tenant) {
+    public TenantInfo getTenantAdmin(
+        @ApiParam(value = "The tenant name")
+        @PathParam("tenant") String tenant) {
         validateSuperUserAccess();
 
         try {
@@ -88,7 +91,10 @@ public TenantInfo getTenantAdmin(@PathParam("tenant") String tenant) {
             @ApiResponse(code = 409, message = "Tenant already exists"),
             @ApiResponse(code = 412, message = "Tenant name is not valid"),
             @ApiResponse(code = 412, message = "Clusters do not exist") })
-    public void createTenant(@PathParam("tenant") String tenant, TenantInfo config) {
+    public void createTenant(
+        @ApiParam(value = "The tenant name")
+        @PathParam("tenant") String tenant,
+        @ApiParam(value = "TenantInfo") TenantInfo config) {
         validateSuperUserAccess();
         validatePoliciesReadOnlyAccess();
         validateClusters(config);
@@ -119,7 +125,10 @@ public void createTenant(@PathParam("tenant") String tenant, TenantInfo config)
             @ApiResponse(code = 404, message = "Tenant does not exist"),
             @ApiResponse(code = 409, message = "Tenant already exists"),
             @ApiResponse(code = 412, message = "Clusters do not exist") })
-    public void updateTenant(@PathParam("tenant") String tenant, TenantInfo newTenantAdmin) {
+    public void updateTenant(
+        @ApiParam(value = "The tenant name")
+        @PathParam("tenant") String tenant,
+        @ApiParam(value = "TenantInfo") TenantInfo newTenantAdmin) {
         validateSuperUserAccess();
         validatePoliciesReadOnlyAccess();
         validateClusters(newTenantAdmin);
@@ -174,7 +183,10 @@ public void updateTenant(@PathParam("tenant") String tenant, TenantInfo newTenan
     @ApiResponses(value = { @ApiResponse(code = 403, message = "The requester doesn't have admin permissions"),
             @ApiResponse(code = 404, message = "Tenant does not exist"),
             @ApiResponse(code = 409, message = "The tenant still has active namespaces") })
-    public void deleteTenant(@PathParam("tenant") String tenant) {
+    public void deleteTenant(
+        @PathParam("tenant")
+        @ApiParam(value = "The tenant name")
+        String tenant) {
         validateSuperUserAccess();
         validatePoliciesReadOnlyAccess();
 

diff --git a/pulsar-common/pom.xml b/pulsar-common/pom.xml
@@ -40,8 +40,8 @@
       <artifactId>pulsar-client-api</artifactId>
       <version>${project.version}</version>
     </dependency>
-    
-  
+
+
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
@@ -93,7 +93,7 @@
       <groupId>org.xerial.snappy</groupId>
       <artifactId>snappy-java</artifactId>
     </dependency>
-    
+
     <dependency>
       <groupId>org.bouncycastle</groupId>
       <artifactId>bcpkix-jdk15on</artifactId>
@@ -120,10 +120,10 @@
       <artifactId>netty-tcnative-boringssl-static</artifactId>
     </dependency>
 
-	<dependency>
-		<groupId>org.eclipse.jetty</groupId>
-		<artifactId>jetty-util</artifactId>
-	</dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-util</artifactId>
+    </dependency>
 
     <dependency>
       <groupId>org.apache.commons</groupId>
@@ -135,6 +135,11 @@
       <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/TenantInfo.java b/pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/TenantInfo.java
@@ -20,20 +20,31 @@
 
 import com.google.common.collect.Sets;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import java.util.Set;
 
 import lombok.Data;
 
 @Data
+@ApiModel(value = "TenantInfo", description = "Information of adminRoles and allowedClusters for tenant")
 public class TenantInfo {
     /**
      * List of role enabled as admin for this tenant
      */
+    @ApiModelProperty(
+        value = "Comma separated list of auth principal allowed to administrate the tenant.",
+        name = "adminRoles"
+    )
     private Set<String> adminRoles;
 
     /**
      * List of clusters this tenant is restricted on
      */
+    @ApiModelProperty(
+        value = "Comma separated allowed clusters.",
+        name = "allowedClusters"
+    )
     private Set<String> allowedClusters;
 
     public TenantInfo() {

diff --git a/pulsar-sql/presto-distribution/LICENSE b/pulsar-sql/presto-distribution/LICENSE
@@ -455,6 +455,8 @@ The Apache Software License, Version 2.0
     - zookeeper-3.4.13.jar
   * Apache Yetus Audience Annotations
     - audience-annotations-0.5.0.jar
+  * Swagger
+    - swagger-annotations-1.5.21.jar
 
 Protocol Buffers License
  * Protocol Buffers