feat: support swagger UI to viewing API (#1880)

implement #1879 Co-authored-by: Yao Wang <[email protected]>
apache · May 16, 2022 · 335f0ea · 335f0ea
1 parent 8609968
commit 335f0ea
Show file tree

Hide file tree

Showing 71 changed files with 296 additions and 1 deletion.
diff --git a/hugegraph-api/pom.xml b/hugegraph-api/pom.xml
@@ -121,6 +121,12 @@
             <artifactId>translation</artifactId>
             <version>1.0.4</version>
         </dependency>
+
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-jaxrs2-jakarta</artifactId>
+            <version>2.1.9</version>
+        </dependency>
     </dependencies>
 
     <build>

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/AccessAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/AccessAPI.java
@@ -21,6 +21,8 @@
 
 import java.util.List;
 
+import io.swagger.annotations.Api;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
 import jakarta.ws.rs.DefaultValue;
@@ -54,6 +56,7 @@
 
 @Path("graphs/{graph}/auth/accesses")
 @Singleton
+@Tag(name = "AccessAPI")
 public class AccessAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/BelongAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/BelongAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
 import jakarta.ws.rs.DefaultValue;
@@ -53,6 +54,7 @@
 
 @Path("graphs/{graph}/auth/belongs")
 @Singleton
+@Tag(name = "BelongAPI")
 public class BelongAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/GroupAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/GroupAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
 import jakarta.ws.rs.DefaultValue;
@@ -53,6 +54,7 @@
 
 @Path("graphs/{graph}/auth/groups")
 @Singleton
+@Tag(name = "GroupAPI")
 public class GroupAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/LoginAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/LoginAPI.java
@@ -19,6 +19,7 @@
 
 package com.baidu.hugegraph.api.auth;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import javax.security.sasl.AuthenticationException;
 import jakarta.ws.rs.BadRequestException;
@@ -55,6 +56,7 @@
 
 @Path("graphs/{graph}/auth")
 @Singleton
+@Tag(name = "LoginAPI")
 public class LoginAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/ProjectAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/ProjectAPI.java
@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Set;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
@@ -58,6 +59,7 @@
 
 @Path("graphs/{graph}/auth/projects")
 @Singleton
+@Tag(name = "ProjectAPI")
 public class ProjectAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/TargetAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/TargetAPI.java
@@ -22,6 +22,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
@@ -54,6 +55,7 @@
 
 @Path("graphs/{graph}/auth/targets")
 @Singleton
+@Tag(name = "TargetAPI")
 public class TargetAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/UserAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/auth/UserAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.DELETE;
@@ -56,6 +57,7 @@
 
 @Path("graphs/{graph}/auth/users")
 @Singleton
+@Tag(name = "UserAPI")
 public class UserAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/filter/ExceptionFilter.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/filter/ExceptionFilter.java
@@ -27,6 +27,7 @@
 import javax.json.JsonArrayBuilder;
 import javax.json.JsonObjectBuilder;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -84,6 +85,7 @@ protected boolean trace() {
 
     @Path("exception/trace")
     @Singleton
+    @Tag(name = "TracedExceptionAPI")
     public static class TracedExceptionAPI extends API {
 
         @GET

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/graph/EdgeAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/graph/EdgeAPI.java
@@ -26,6 +26,7 @@
 import java.util.Map;
 import java.util.NoSuchElementException;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -75,6 +76,7 @@
 
 @Path("graphs/{graph}/graph/edges")
 @Singleton
+@Tag(name = "EdgeAPI")
 public class EdgeAPI extends BatchAPI {
 
     private static final Logger LOG = Log.logger(EdgeAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/graph/VertexAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/graph/VertexAPI.java
@@ -27,6 +27,7 @@
 import java.util.Map;
 import java.util.NoSuchElementException;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -74,6 +75,7 @@
 
 @Path("graphs/{graph}/graph/vertices")
 @Singleton
+@Tag(name = "VertexAPI")
 public class VertexAPI extends BatchAPI {
 
     private static final Logger LOG = Log.logger(VertexAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/gremlin/CypherAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/gremlin/CypherAPI.java
@@ -8,6 +8,7 @@
 import com.baidu.hugegraph.util.Log;
 import com.codahale.metrics.annotation.Timed;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.GET;
@@ -22,6 +23,7 @@
 
 @Path("graphs/{graph}/cypher")
 @Singleton
+@Tag(name = "CypherAPI")
 public class CypherAPI extends GremlinQueryAPI {
 
     private static final Logger LOG = Log.logger(CypherAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/gremlin/GremlinAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/gremlin/GremlinAPI.java
@@ -22,6 +22,7 @@
 import java.util.Map;
 import java.util.Set;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.POST;
@@ -49,6 +50,7 @@
 
 @Path("gremlin")
 @Singleton
+@Tag(name = "GremlinAPI")
 public class GremlinAPI extends GremlinQueryAPI {
 
     private static final Histogram GREMLIN_INPUT_HISTOGRAM =

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/ComputerAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/ComputerAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.NotFoundException;
@@ -49,6 +50,7 @@
 
 @Path("graphs/{graph}/jobs/computer")
 @Singleton
+@Tag(name = "ComputerAPI")
 public class ComputerAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/GremlinAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/GremlinAPI.java
@@ -27,6 +27,7 @@
 import java.util.HashMap;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -59,6 +60,7 @@
 
 @Path("graphs/{graph}/jobs/gremlin")
 @Singleton
+@Tag(name = "GremlinAPI")
 public class GremlinAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/RebuildAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/RebuildAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.PUT;
@@ -42,6 +43,7 @@
 
 @Path("graphs/{graph}/jobs/rebuild")
 @Singleton
+@Tag(name = "RebuildAPI")
 public class RebuildAPI extends API {
 
     private static final Logger LOG = Log.logger(RebuildAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/TaskAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/job/TaskAPI.java
@@ -26,6 +26,7 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.BadRequestException;
 import jakarta.ws.rs.DELETE;
@@ -58,6 +59,7 @@
 
 @Path("graphs/{graph}/tasks")
 @Singleton
+@Tag(name = "TaskAPI")
 public class TaskAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/metrics/MetricsAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/metrics/MetricsAPI.java
@@ -25,6 +25,7 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.GET;
@@ -49,6 +50,7 @@
 
 @Singleton
 @Path("metrics")
+@Tag(name = "MetricsAPI")
 public class MetricsAPI extends API {
 
     private static final Logger LOG = Log.logger(MetricsAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/GraphsAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/GraphsAPI.java
@@ -24,6 +24,8 @@
 import java.util.Map;
 import java.util.Set;
 
+import io.swagger.annotations.Api;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -60,6 +62,7 @@
 
 @Path("graphs")
 @Singleton
+@Tag(name = "GraphsAPI")
 public class GraphsAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/ProfileAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/ProfileAPI.java
@@ -26,6 +26,7 @@
 import java.util.TreeMap;
 import java.util.TreeSet;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
@@ -49,6 +50,7 @@
 
 @Path("/")
 @Singleton
+@Tag(name = "ProfileAPI")
 public class ProfileAPI {
 
     private static final String SERVICE = "hugegraph";

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/VersionAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/profile/VersionAPI.java
@@ -21,6 +21,7 @@
 
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.PermitAll;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.GET;
@@ -35,6 +36,7 @@
 
 @Path("versions")
 @Singleton
+@Tag(name = "VersionAPI")
 public class VersionAPI extends API {
 
     @GET

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/raft/RaftAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/raft/RaftAPI.java
@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -55,6 +56,7 @@
 
 @Path("graphs/{graph}/raft")
 @Singleton
+@Tag(name = "RaftAPI")
 public class RaftAPI extends API {
 
     private static final Logger LOG = Log.logger(RaftAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/EdgeLabelAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/EdgeLabelAPI.java
@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -58,6 +59,7 @@
 
 @Path("graphs/{graph}/schema/edgelabels")
 @Singleton
+@Tag(name = "EdgeLabelAPI")
 public class EdgeLabelAPI extends API {
 
     private static final Logger LOG = Log.logger(EdgeLabelAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/IndexLabelAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/IndexLabelAPI.java
@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -60,6 +61,7 @@
 
 @Path("graphs/{graph}/schema/indexlabels")
 @Singleton
+@Tag(name = "IndexLabelAPI")
 public class IndexLabelAPI extends API {
 
     private static final Logger LOG = Log.logger(IndexLabelAPI.class);

diff --git a/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/PropertyKeyAPI.java b/hugegraph-api/src/main/java/com/baidu/hugegraph/api/schema/PropertyKeyAPI.java
@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Map;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -63,6 +64,7 @@
 
 @Path("graphs/{graph}/schema/propertykeys")
 @Singleton
+@Tag(name = "PropertyKeyAPI")
 public class PropertyKeyAPI extends API {
 
     private static final Logger LOG = Log.logger(PropertyKeyAPI.class);