chore(api): add swagger desc for Arthas & Metric & Cypher & White API (…

…apache#2337) add swagger belong for arthas API --------- Co-authored-by: imbajin <[email protected]>
VGalaxies · Nov 10, 2023 · 2cd1269 · 2cd1269
1 parent 5b8ac6f
commit 2cd1269
Show file tree

Hide file tree

Showing 9 changed files with 49 additions and 17 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -20,7 +20,7 @@ jobs:
       HEAD_BRANCH_NAME: ${{ github.head_ref }}
       BASE_BRANCH_NAME: ${{ github.base_ref }}
       TARGET_BRANCH_NAME: ${{ github.base_ref != '' && github.base_ref || github.ref_name }}
-      RELEASE_BRANCH: ${{ startsWith(github.ref_name, 'release-') || startsWith(github.ref_name, 'test-') || startsWith(github.base_ref, 'release-') }}
+      RELEASE_BRANCH: ${{ startsWith(github.ref_name, 'release-') || startsWith(github.ref_name, 'test-') }}
 
     strategy:
       fail-fast: false
@@ -43,7 +43,7 @@ jobs:
           restore-keys: ${{ runner.os }}-m2
 
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 2
 
@@ -98,6 +98,6 @@ jobs:
           $TRAVIS_DIR/run-tinkerpop-test.sh $BACKEND tinkerpop
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3.0.0
+        uses: codecov/codecov-action@v3
         with:
           file: ${{ env.REPORT_DIR }}/*.xml
diff --git a/hugegraph-server/hugegraph-api/pom.xml b/hugegraph-server/hugegraph-api/pom.xml
@@ -151,7 +151,7 @@
         <dependency>
             <groupId>io.swagger.core.v3</groupId>
             <artifactId>swagger-jaxrs2-jakarta</artifactId>
-            <version>2.1.9</version>
+            <version>${swagger.version}</version>
         </dependency>
 
         <dependency>

diff --git a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/arthas/ArthasAPI.java b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/arthas/ArthasAPI.java
@@ -27,6 +27,9 @@
 import com.codahale.metrics.annotation.Timed;
 import com.taobao.arthas.agent.attach.ArthasAgent;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.PUT;
 import jakarta.ws.rs.Path;
@@ -35,6 +38,7 @@
 
 @Path("arthas")
 @Singleton
+@Tag(name = "ArthasAPI")
 public class ArthasAPI extends API {
 
     @Context
@@ -43,6 +47,7 @@ public class ArthasAPI extends API {
     @PUT
     @Timed
     @Produces(APPLICATION_JSON_WITH_CHARSET)
+    @Operation(summary = "start arthas agent")
     public Object startArthas() {
         HugeConfig config = this.configProvider.get();
         HashMap<String, String> configMap = new HashMap<>(4);

diff --git a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java
@@ -33,6 +33,8 @@
 
 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;
@@ -47,6 +49,7 @@
 
 @Path("graphs/{graph}/cypher")
 @Singleton
+@Tag(name = "CypherAPI")
 public class CypherAPI extends API {
 
     private static final Logger LOG = Log.logger(CypherAPI.class);

diff --git a/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java b/hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java
@@ -36,6 +36,8 @@
 import com.codahale.metrics.annotation.Timed;
 import com.google.common.collect.ImmutableMap;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
+
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
 import jakarta.ws.rs.NotFoundException;
@@ -47,6 +49,7 @@
 
 @Path("graphs/{graph}/jobs/algorithm")
 @Singleton
+@Tag(name = "AlgorithmAPI")
 public class AlgorithmAPI extends API {
 
     private static final Logger LOG = Log.logger(RestServer.class);

diff --git a/...graph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java b/...graph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java
@@ -70,7 +70,9 @@
 import com.codahale.metrics.Metric;
 import com.codahale.metrics.annotation.Timed;
 
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
+
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.GET;
@@ -103,6 +105,7 @@ public MetricsAPI() {
     @Path("system")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the system metrics")
     public String system() {
         return JsonUtil.toJson(this.systemMetrics.metrics());
     }
@@ -112,6 +115,7 @@ public String system() {
     @Path("backend")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the backend metrics")
     public String backend(@Context GraphManager manager) {
         Map<String, Map<String, Object>> results = InsertionOrderUtil.newMap();
         for (String graph : manager.graphs()) {
@@ -134,6 +138,7 @@ public String backend(@Context GraphManager manager) {
     @Path("gauges")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the gauges metrics")
     public String gauges() {
         ServerReporter reporter = ServerReporter.instance();
         return JsonUtil.toJson(reporter.gauges());
@@ -144,6 +149,7 @@ public String gauges() {
     @Path("counters")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the counters metrics")
     public String counters() {
         ServerReporter reporter = ServerReporter.instance();
         return JsonUtil.toJson(reporter.counters());
@@ -154,6 +160,7 @@ public String counters() {
     @Path("histograms")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the histograms metrics")
     public String histograms() {
         ServerReporter reporter = ServerReporter.instance();
         return JsonUtil.toJson(reporter.histograms());
@@ -164,6 +171,7 @@ public String histograms() {
     @Path("meters")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the meters metrics")
     public String meters() {
         ServerReporter reporter = ServerReporter.instance();
         return JsonUtil.toJson(reporter.meters());
@@ -174,6 +182,7 @@ public String meters() {
     @Path("timers")
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get the timers metrics")
     public String timers() {
         ServerReporter reporter = ServerReporter.instance();
         return JsonUtil.toJson(reporter.timers());
@@ -183,6 +192,7 @@ public String timers() {
     @Timed
     @Produces(APPLICATION_TEXT_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get all base metrics")
     public String all(@Context GraphManager manager,
                       @QueryParam("type") String type) {
         if (type != null && type.equals(JSON_STR)) {
@@ -197,6 +207,7 @@ public String all(@Context GraphManager manager,
     @Timed
     @Produces(APPLICATION_TEXT_WITH_CHARSET)
     @RolesAllowed({"admin", "$owner= $action=metrics_read"})
+    @Operation(summary = "get all statistics metrics")
     public String statistics(@QueryParam("type") String type) {
         Map<String, Map<String, Object>> metricMap = statistics();
 

diff --git a/...h-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java b/...h-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java
@@ -37,6 +37,8 @@
 import com.codahale.metrics.annotation.Timed;
 import com.google.common.collect.ImmutableMap;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.security.RolesAllowed;
 import jakarta.inject.Singleton;
 import jakarta.ws.rs.Consumes;
@@ -50,6 +52,7 @@
 
 @Path("whiteiplist")
 @Singleton
+@Tag(name = "WhiteIpListAPI")
 public class WhiteIpListAPI extends API {
 
     private static final Logger LOG = Log.logger(WhiteIpListAPI.class);
@@ -58,6 +61,7 @@ public class WhiteIpListAPI extends API {
     @Timed
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed("admin")
+    @Operation(summary = "list white ips")
     public Map<String, Object> list(@Context GraphManager manager) {
         LOG.debug("List white ips");
         AuthManager authManager = manager.authManager();
@@ -71,6 +75,7 @@ public Map<String, Object> list(@Context GraphManager manager) {
     @Consumes(APPLICATION_JSON)
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed("admin")
+    @Operation(summary = "update white ip list")
     public Map<String, Object> updateWhiteIPs(@Context GraphManager manager, Map<String, Object> actionMap) {
         E.checkArgument(actionMap != null,
                         "Missing argument: actionMap");
@@ -131,6 +136,7 @@ public Map<String, Object> updateWhiteIPs(@Context GraphManager manager, Map<Str
     @Timed
     @Produces(APPLICATION_JSON_WITH_CHARSET)
     @RolesAllowed("admin")
+    @Operation(summary = "enable/disable the white ip list")
     public Map<String, Object> updateStatus(@Context GraphManager manager, @QueryParam("status") String status) {
         LOG.debug("Enable or disable white ip list");
         E.checkArgument("true".equals(status) ||

diff --git a/hugegraph-server/hugegraph-dist/scripts/dependency/known-dependencies.txt b/hugegraph-server/hugegraph-dist/scripts/dependency/known-dependencies.txt
@@ -32,7 +32,7 @@ chronicle-core-2.20.126.jar
 chronicle-queue-5.20.123.jar
 chronicle-threads-2.20.111.jar
 chronicle-wire-2.20.117.jar
-classgraph-4.8.95.jar
+classgraph-4.8.162.jar
 commons-beanutils-1.9.4.jar
 commons-cli-1.1.jar
 commons-codec-1.11.jar
@@ -112,14 +112,16 @@ jackson-annotations-2.13.2.jar
 jackson-annotations-2.14.0-rc1.jar
 jackson-core-2.13.2.jar
 jackson-core-2.14.0-rc1.jar
-jackson-databind-2.12.1.jar
 jackson-databind-2.13.2.2.jar
 jackson-databind-2.14.0-rc1.jar
+jackson-databind-2.15.2.jar
 jackson-dataformat-yaml-2.9.3.jar
-jackson-datatype-jsr310-2.12.1.jar
+jackson-datatype-jsr310-2.15.2.jar
+jackson-jakarta-rs-base-2.15.2.jar
+jackson-jakarta-rs-json-provider-2.15.2.jar
 jackson-jaxrs-base-2.14.0-rc1.jar
-jackson-jaxrs-json-provider-2.12.1-jakarta.jar
 jackson-jaxrs-json-provider-2.14.0-rc1.jar
+jackson-module-jakarta-xmlbind-annotations-2.15.2.jar
 jackson-module-jaxb-annotations-2.14.0-rc1.jar
 jakarta.activation-2.0.1.jar
 jakarta.activation-api-1.2.2.jar
@@ -131,7 +133,6 @@ jakarta.ws.rs-api-3.0.0.jar
 jakarta.xml.bind-api-4.0.0-RC2.jar
 jamm-0.3.2.jar
 java-cup-runtime-11b-20160615.jar
-jcommander-1.30.jar
 javapoet-1.8.0.jar
 javassist-3.21.0-GA.jar
 javatuples-1.2.jar
@@ -146,6 +147,7 @@ jcabi-log-0.14.jar
 jcabi-manifests-1.1.jar
 jcip-annotations-1.0-1.jar
 jcl-over-slf4j-1.7.25.jar
+jcommander-1.30.jar
 jcseg-core-2.6.2.jar
 jctools-core-2.1.1.jar
 jctools-core-3.1.0.jar
@@ -175,12 +177,12 @@ jna-5.12.1.jar
 jnr-ffi-2.1.7.jar
 jnr-x86asm-1.0.2.jar
 joda-time-2.10.8.jar
-jvm-attach-api-1.5.jar
 jraft-core-1.3.11.jar
 json-simple-1.1.jar
 json-smart-2.3.jar
 jsr305-3.0.1.jar
 junit-4.12.jar
+jvm-attach-api-1.5.jar
 kerb-admin-2.0.0.jar
 kerb-client-2.0.0.jar
 kerb-common-2.0.0.jar
@@ -245,33 +247,34 @@ rocksdbjni-7.2.2.jar
 scala-java8-compat_2.12-0.8.0.jar
 scala-library-2.12.7.jar
 scala-reflect-2.12.7.jar
+sigar-1.6.4.jar
 sjk-cli-0.14.jar
 sjk-core-0.14.jar
 sjk-json-0.14.jar
 sjk-stacktrace-0.14.jar
-sigar-1.6.4.jar
 slf4j-api-1.7.25.jar
 snakeyaml-1.26.jar
 snakeyaml-1.27.jar
+snakeyaml-2.2.jar
 snappy-java-1.1.2.6.jar
 snowball-stemmer-1.3.0.581.1.jar
 sofa-common-tools-1.0.12.jar
 sofa-rpc-all-5.7.6.jar
 sourcecode_2.12-0.1.4.jar
 stream-2.5.2.jar
 swagger-annotations-1.5.18.jar
-swagger-annotations-jakarta-2.1.9.jar
+swagger-annotations-jakarta-2.2.18.jar
 swagger-core-1.5.18.jar
-swagger-core-jakarta-2.1.9.jar
-swagger-integration-jakarta-2.1.9.jar
-swagger-jaxrs2-jakarta-2.1.9.jar
+swagger-core-jakarta-2.2.18.jar
+swagger-integration-jakarta-2.2.18.jar
+swagger-jaxrs2-jakarta-2.2.18.jar
 swagger-models-1.5.18.jar
-swagger-models-jakarta-2.1.9.jar
+swagger-models-jakarta-2.2.18.jar
 tinkergraph-gremlin-3.5.1.jar
 token-provider-2.0.0.jar
 tracer-core-3.0.8.jar
 translation-1.0.4.jar
 util-9.0-9.0.20190305.jar
 validation-api-1.1.0.Final.jar
-zt-zip-1.14.jar
 zstd-jni-1.5.5-1.jar
+zt-zip-1.14.jar
diff --git a/hugegraph-server/pom.xml b/hugegraph-server/pom.xml
@@ -115,6 +115,7 @@
         <protobuf.version>3.21.7</protobuf.version>
         <jmh.version>1.36</jmh.version>
         <arthas.version>3.7.1</arthas.version>
+        <swagger.version>2.2.18</swagger.version>
     </properties>
 
     <modules>