chore(api): add swagger desc for Arthas & Metric & Cypher & White API (#2337)
add swagger belong for arthas API
---------
Co-authored-by: imbajin <jin@apache.org>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 414fd4a..b67021f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@
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
@@ -42,7 +42,7 @@
restore-keys: ${{ runner.os }}-m2
- name: Checkout
- uses: actions/checkout@v3
+ uses: actions/checkout@v4
with:
fetch-depth: 2
@@ -88,6 +88,6 @@
$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-api/pom.xml b/hugegraph-api/pom.xml
index b99cde5..ad397f1 100644
--- a/hugegraph-api/pom.xml
+++ b/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-api/src/main/java/org/apache/hugegraph/api/arthas/ArthasAPI.java b/hugegraph-api/src/main/java/org/apache/hugegraph/api/arthas/ArthasAPI.java
index 549f9de..67e65a3 100644
--- a/hugegraph-api/src/main/java/org/apache/hugegraph/api/arthas/ArthasAPI.java
+++ b/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 @@
@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-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java b/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java
index bf43d6a..0018bcd 100644
--- a/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java
+++ b/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-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java b/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java
index 8e0e7d1..8341ada 100644
--- a/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java
+++ b/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/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java b/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java
index f74286b..952ac90 100644
--- a/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java
+++ b/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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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 @@
@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/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java b/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java
index 7503e13..860da55 100644
--- a/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java
+++ b/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 @@
@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 @@
@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 @@
@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-dist/scripts/dependency/known-dependencies.txt b/hugegraph-dist/scripts/dependency/known-dependencies.txt
index f138843..d40b204 100644
--- a/hugegraph-dist/scripts/dependency/known-dependencies.txt
+++ b/hugegraph-dist/scripts/dependency/known-dependencies.txt
@@ -32,7 +32,7 @@
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.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.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-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 @@
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,14 +247,15 @@
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
@@ -260,18 +263,18 @@
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/pom.xml b/pom.xml
index 242263c..270182e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -116,6 +116,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>
