Skip to content

refactor: add the desc of the vars in swagger-ui #2969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
imbajin merged 8 commits into from
Mar 16, 2026
Merged

refactor: add the desc of the vars in swagger-ui #2969

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b367e01
add: add des for var
lokidundun Mar 14, 2026
c6e4b79
remove unuse file
lokidundun Mar 14, 2026
94609b6
optimize: formate the code style
lokidundun Mar 14, 2026
b5609ab
optimize: formate the code style
lokidundun Mar 14, 2026
3b8d349
optimize: format the code style
lokidundun Mar 15, 2026
d21ccae
optimize: format the code style
lokidundun Mar 15, 2026
931e905
optimize: change some des
lokidundun Mar 16, 2026
3230fb1
optimize: decline some des
lokidundun Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.inject.Singleton;
import jakarta.ws.rs.Consumes;
Expand Down Expand Up @@ -62,7 +64,7 @@ public class AccessAPI extends API {
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String create(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
JsonAccess jsonAccess) {
LOG.debug("GraphSpace [{}] create access: {}", graphSpace, jsonAccess);
checkCreatingBody(jsonAccess);
Expand All @@ -78,8 +80,8 @@ public String create(@Context GraphManager manager,
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String update(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id,
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The access id") @PathParam("id") String id,
JsonAccess jsonAccess) {
LOG.debug("GraphSpace [{}] update access: {}", graphSpace, jsonAccess);
checkUpdatingBody(jsonAccess);
Expand All @@ -99,10 +101,10 @@ public String update(@Context GraphManager manager,
@Timed
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String list(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("group") String group,
@QueryParam("target") String target,
@QueryParam("limit") @DefaultValue("100") long limit) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The group id to filter by") @QueryParam("group") String group,
@Parameter(description = "The target id to filter by") @QueryParam("target") String target,
@Parameter(description = "The limit of results to return") @QueryParam("limit") @DefaultValue("100") long limit) {
LOG.debug("GraphSpace [{}] list accesses by group {} or target {}",
graphSpace, group, target);
E.checkArgument(group == null || target == null,
Expand All @@ -126,8 +128,8 @@ public String list(@Context GraphManager manager,
@Path("{id}")
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String get(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The access id") @PathParam("id") String id) {
LOG.debug("GraphSpace [{}] get access: {}", graphSpace, id);

HugeAccess access = manager.authManager().getAccess(UserAPI.parseId(id));
Expand All @@ -139,8 +141,8 @@ public String get(@Context GraphManager manager,
@Path("{id}")
@Consumes(APPLICATION_JSON)
public void delete(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The access id") @PathParam("id") String id) {
LOG.debug("GraphSpace [{}] delete access: {}", graphSpace, id);

try {
Expand All @@ -155,12 +157,16 @@ public void delete(@Context GraphManager manager,
private static class JsonAccess implements Checkable {

@JsonProperty("group")
@Schema(description = "The group id", required = true)
private String group;
@JsonProperty("target")
@Schema(description = "The target id", required = true)
private String target;
@JsonProperty("access_permission")
@Schema(description = "The access permission", required = true)
private HugePermission permission;
@JsonProperty("access_description")
@Schema(description = "The access description")
private String description;

public HugeAccess build(HugeAccess access) {
Expand Down
27 changes: 16 additions & 11 deletions hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.inject.Singleton;
import jakarta.ws.rs.Consumes;
Expand Down Expand Up @@ -61,7 +63,7 @@ public class BelongAPI extends API {
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String create(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
JsonBelong jsonBelong) {
LOG.debug("GraphSpace [{}] create belong: {}", graphSpace, jsonBelong);
checkCreatingBody(jsonBelong);
Expand All @@ -77,8 +79,8 @@ public String create(@Context GraphManager manager,
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String update(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id,
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The belong id") @PathParam("id") String id,
JsonBelong jsonBelong) {
LOG.debug("GraphSpace [{}] update belong: {}", graphSpace, jsonBelong);
checkUpdatingBody(jsonBelong);
Expand All @@ -98,10 +100,10 @@ public String update(@Context GraphManager manager,
@Timed
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String list(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("user") String user,
@QueryParam("group") String group,
@QueryParam("limit") @DefaultValue("100") long limit) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The user id to filter by") @QueryParam("user") String user,
@Parameter(description = "The group id to filter by") @QueryParam("group") String group,
@Parameter(description = "The limit of results to return") @QueryParam("limit") @DefaultValue("100") long limit) {
LOG.debug("GraphSpace [{}] list belongs by user {} or group {}",
graphSpace, user, group);
E.checkArgument(user == null || group == null,
Expand All @@ -125,8 +127,8 @@ public String list(@Context GraphManager manager,
@Path("{id}")
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String get(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The belong id") @PathParam("id") String id) {
LOG.debug("GraphSpace [{}] get belong: {}", graphSpace, id);

HugeBelong belong = manager.authManager().getBelong(UserAPI.parseId(id));
Expand All @@ -138,8 +140,8 @@ public String get(@Context GraphManager manager,
@Path("{id}")
@Consumes(APPLICATION_JSON)
public void delete(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@PathParam("id") String id) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The belong id") @PathParam("id") String id) {
LOG.debug("GraphSpace [{}] delete belong: {}", graphSpace, id);

try {
Expand All @@ -154,10 +156,13 @@ public void delete(@Context GraphManager manager,
private static class JsonBelong implements Checkable {

@JsonProperty("user")
@Schema(description = "The user id", required = true)
private String user;
@JsonProperty("group")
@Schema(description = "The group id", required = true)
private String group;
@JsonProperty("belong_description")
@Schema(description = "The belong description")
private String description;

public HugeBelong build(HugeBelong belong) {
Expand Down
12 changes: 8 additions & 4 deletions hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Singleton;
Expand Down Expand Up @@ -79,7 +81,7 @@ public String create(@Context GraphManager manager,
@Produces(APPLICATION_JSON_WITH_CHARSET)
@RolesAllowed({"admin"})
public String update(@Context GraphManager manager,
@PathParam("id") String id,
@Parameter(description = "The group id") @PathParam("id") String id,
JsonGroup jsonGroup) {
LOG.debug("update group: {}", jsonGroup);
checkUpdatingBody(jsonGroup);
Expand All @@ -100,7 +102,7 @@ public String update(@Context GraphManager manager,
@Produces(APPLICATION_JSON_WITH_CHARSET)
@RolesAllowed({"admin"})
public String list(@Context GraphManager manager,
@QueryParam("limit") @DefaultValue("100") long limit) {
@Parameter(description = "The limit of results to return") @QueryParam("limit") @DefaultValue("100") long limit) {
LOG.debug("list groups");
Comment on lines 105 to 108

List<HugeGroup> groups = manager.authManager().listAllGroups(limit);
Expand All @@ -113,7 +115,7 @@ public String list(@Context GraphManager manager,
@Produces(APPLICATION_JSON_WITH_CHARSET)
@RolesAllowed({"admin"})
public String get(@Context GraphManager manager,
@PathParam("id") String id) {
@Parameter(description = "The group id") @PathParam("id") String id) {
LOG.debug("get group: {}", id);

HugeGroup group = manager.authManager().getGroup(IdGenerator.of(id));
Expand All @@ -126,7 +128,7 @@ public String get(@Context GraphManager manager,
@Consumes(APPLICATION_JSON)
@RolesAllowed({"admin"})
public void delete(@Context GraphManager manager,
@PathParam("id") String id) {
@Parameter(description = "The group id") @PathParam("id") String id) {
LOG.debug("delete group: {}", id);

try {
Expand All @@ -141,8 +143,10 @@ public void delete(@Context GraphManager manager,
private static class JsonGroup implements Checkable {

@JsonProperty("group_name")
@Schema(description = "The group name", required = true)
private String name;
@JsonProperty("group_description")
@Schema(description = "The group description")
private String description;

public HugeGroup build(HugeGroup group) {
Expand Down
5 changes: 5 additions & 0 deletions hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@
import com.fasterxml.jackson.annotation.JsonProperty;
import com.google.common.collect.ImmutableMap;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.inject.Singleton;
import jakarta.ws.rs.BadRequestException;
Expand Down Expand Up @@ -125,10 +127,13 @@ public String verifyToken(@Context GraphManager manager,
private static class JsonLogin implements Checkable {

@JsonProperty("user_name")
@Schema(description = "The user name")
private String name;
@JsonProperty("user_password")
@Schema(description = "The user password")
private String password;
@JsonProperty("token_expire")
@Schema(description = "Token expiration time in seconds")
private long expire;

@Override
Expand Down
24 changes: 14 additions & 10 deletions hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@
import com.fasterxml.jackson.annotation.JsonProperty;
import com.google.common.collect.ImmutableMap;

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.inject.Singleton;
import jakarta.ws.rs.Consumes;
Expand All @@ -62,7 +64,7 @@ public class ManagerAPI extends API {
@Consumes(APPLICATION_JSON)
@Produces(APPLICATION_JSON_WITH_CHARSET)
public String createManager(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
JsonManager jsonManager) {
LOG.debug("Create manager: {}", jsonManager);
String user = jsonManager.user;
Expand Down Expand Up @@ -113,9 +115,9 @@ public String createManager(@Context GraphManager manager,
@Timed
@Consumes(APPLICATION_JSON)
public void delete(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("user") String user,
@QueryParam("type") HugePermission type) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The user name") @QueryParam("user") String user,
@Parameter(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN") @QueryParam("type") HugePermission type) {
LOG.debug("Delete graph manager: {} {} {}", user, type, graphSpace);
E.checkArgument(!"admin".equals(user) ||
type != HugePermission.ADMIN,
Expand Down Expand Up @@ -157,8 +159,8 @@ public void delete(@Context GraphManager manager,
@Timed
@Consumes(APPLICATION_JSON)
public String list(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("type") HugePermission type) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN") @QueryParam("type") HugePermission type) {
LOG.debug("list graph manager: {} {}", type, graphSpace);

AuthManager authManager = manager.authManager();
Expand Down Expand Up @@ -187,8 +189,8 @@ public String list(@Context GraphManager manager,
@Path("check")
@Consumes(APPLICATION_JSON)
public String checkRole(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("type") HugePermission type) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN") @QueryParam("type") HugePermission type) {
LOG.debug("check if current user is graph manager: {} {}", type, graphSpace);

validType(type);
Expand Down Expand Up @@ -219,8 +221,8 @@ public String checkRole(@Context GraphManager manager,
@Path("role")
@Consumes(APPLICATION_JSON)
public String getRolesInGs(@Context GraphManager manager,
@PathParam("graphspace") String graphSpace,
@QueryParam("user") String user) {
@Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
@Parameter(description = "The user name") @QueryParam("user") String user) {
LOG.debug("get user [{}]'s role in graph space [{}]", user, graphSpace);
AuthManager authManager = manager.authManager();
List<HugePermission> result = new ArrayList<>();
Expand Down Expand Up @@ -264,8 +266,10 @@ private void validGraphSpace(GraphManager manager, String graphSpace) {
private static class JsonManager implements Checkable {

@JsonProperty("user")
@Schema(description = "The user or group name", required = true)
private String user;
@JsonProperty("type")
@Schema(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN", required = true)
private HugePermission type;

@Override
Expand Down
Loading
Loading