Skip to content

Commit 5578b79

Browse files
lokidundunlokidundun
authored
refactor: add the desc of the vars in swagger-ui (#2969)
1 parent 94c03a9 commit 5578b79

39 files changed

Lines changed: 622 additions & 26 deletions

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@
3535
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
3636
import com.fasterxml.jackson.annotation.JsonProperty;
3737

38+
import io.swagger.v3.oas.annotations.Parameter;
39+
import io.swagger.v3.oas.annotations.media.Schema;
3840
import io.swagger.v3.oas.annotations.tags.Tag;
3941
import jakarta.inject.Singleton;
4042
import jakarta.ws.rs.Consumes;
@@ -62,6 +64,7 @@ public class AccessAPI extends API {
6264
@Consumes(APPLICATION_JSON)
6365
@Produces(APPLICATION_JSON_WITH_CHARSET)
6466
public String create(@Context GraphManager manager,
67+
@Parameter(description = "The graph space name")
6568
@PathParam("graphspace") String graphSpace,
6669
JsonAccess jsonAccess) {
6770
LOG.debug("GraphSpace [{}] create access: {}", graphSpace, jsonAccess);
@@ -78,7 +81,9 @@ public String create(@Context GraphManager manager,
7881
@Consumes(APPLICATION_JSON)
7982
@Produces(APPLICATION_JSON_WITH_CHARSET)
8083
public String update(@Context GraphManager manager,
84+
@Parameter(description = "The graph space name")
8185
@PathParam("graphspace") String graphSpace,
86+
@Parameter(description = "The access id")
8287
@PathParam("id") String id,
8388
JsonAccess jsonAccess) {
8489
LOG.debug("GraphSpace [{}] update access: {}", graphSpace, jsonAccess);
@@ -99,9 +104,13 @@ public String update(@Context GraphManager manager,
99104
@Timed
100105
@Produces(APPLICATION_JSON_WITH_CHARSET)
101106
public String list(@Context GraphManager manager,
107+
@Parameter(description = "The graph space name")
102108
@PathParam("graphspace") String graphSpace,
109+
@Parameter(description = "The group id to filter by")
103110
@QueryParam("group") String group,
111+
@Parameter(description = "The target id to filter by")
104112
@QueryParam("target") String target,
113+
@Parameter(description = "The limit of results to return")
105114
@QueryParam("limit") @DefaultValue("100") long limit) {
106115
LOG.debug("GraphSpace [{}] list accesses by group {} or target {}",
107116
graphSpace, group, target);
@@ -126,7 +135,9 @@ public String list(@Context GraphManager manager,
126135
@Path("{id}")
127136
@Produces(APPLICATION_JSON_WITH_CHARSET)
128137
public String get(@Context GraphManager manager,
138+
@Parameter(description = "The graph space name")
129139
@PathParam("graphspace") String graphSpace,
140+
@Parameter(description = "The access id")
130141
@PathParam("id") String id) {
131142
LOG.debug("GraphSpace [{}] get access: {}", graphSpace, id);
132143

@@ -139,7 +150,9 @@ public String get(@Context GraphManager manager,
139150
@Path("{id}")
140151
@Consumes(APPLICATION_JSON)
141152
public void delete(@Context GraphManager manager,
153+
@Parameter(description = "The graph space name")
142154
@PathParam("graphspace") String graphSpace,
155+
@Parameter(description = "The access id")
143156
@PathParam("id") String id) {
144157
LOG.debug("GraphSpace [{}] delete access: {}", graphSpace, id);
145158

@@ -155,12 +168,16 @@ public void delete(@Context GraphManager manager,
155168
private static class JsonAccess implements Checkable {
156169

157170
@JsonProperty("group")
171+
@Schema(description = "The group id", required = true)
158172
private String group;
159173
@JsonProperty("target")
174+
@Schema(description = "The target id", required = true)
160175
private String target;
161176
@JsonProperty("access_permission")
177+
@Schema(description = "The access permission", required = true)
162178
private HugePermission permission;
163179
@JsonProperty("access_description")
180+
@Schema(description = "The access description")
164181
private String description;
165182

166183
public HugeAccess build(HugeAccess access) {

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
3535
import com.fasterxml.jackson.annotation.JsonProperty;
3636

37+
import io.swagger.v3.oas.annotations.Parameter;
38+
import io.swagger.v3.oas.annotations.media.Schema;
3739
import io.swagger.v3.oas.annotations.tags.Tag;
3840
import jakarta.inject.Singleton;
3941
import jakarta.ws.rs.Consumes;
@@ -61,6 +63,7 @@ public class BelongAPI extends API {
6163
@Consumes(APPLICATION_JSON)
6264
@Produces(APPLICATION_JSON_WITH_CHARSET)
6365
public String create(@Context GraphManager manager,
66+
@Parameter(description = "The graph space name")
6467
@PathParam("graphspace") String graphSpace,
6568
JsonBelong jsonBelong) {
6669
LOG.debug("GraphSpace [{}] create belong: {}", graphSpace, jsonBelong);
@@ -77,7 +80,9 @@ public String create(@Context GraphManager manager,
7780
@Consumes(APPLICATION_JSON)
7881
@Produces(APPLICATION_JSON_WITH_CHARSET)
7982
public String update(@Context GraphManager manager,
83+
@Parameter(description = "The graph space name")
8084
@PathParam("graphspace") String graphSpace,
85+
@Parameter(description = "The belong id")
8186
@PathParam("id") String id,
8287
JsonBelong jsonBelong) {
8388
LOG.debug("GraphSpace [{}] update belong: {}", graphSpace, jsonBelong);
@@ -98,9 +103,13 @@ public String update(@Context GraphManager manager,
98103
@Timed
99104
@Produces(APPLICATION_JSON_WITH_CHARSET)
100105
public String list(@Context GraphManager manager,
106+
@Parameter(description = "The graph space name")
101107
@PathParam("graphspace") String graphSpace,
108+
@Parameter(description = "The user id to filter by")
102109
@QueryParam("user") String user,
110+
@Parameter(description = "The group id to filter by")
103111
@QueryParam("group") String group,
112+
@Parameter(description = "The limit of results to return")
104113
@QueryParam("limit") @DefaultValue("100") long limit) {
105114
LOG.debug("GraphSpace [{}] list belongs by user {} or group {}",
106115
graphSpace, user, group);
@@ -125,7 +134,9 @@ public String list(@Context GraphManager manager,
125134
@Path("{id}")
126135
@Produces(APPLICATION_JSON_WITH_CHARSET)
127136
public String get(@Context GraphManager manager,
137+
@Parameter(description = "The graph space name")
128138
@PathParam("graphspace") String graphSpace,
139+
@Parameter(description = "The belong id")
129140
@PathParam("id") String id) {
130141
LOG.debug("GraphSpace [{}] get belong: {}", graphSpace, id);
131142

@@ -138,7 +149,9 @@ public String get(@Context GraphManager manager,
138149
@Path("{id}")
139150
@Consumes(APPLICATION_JSON)
140151
public void delete(@Context GraphManager manager,
152+
@Parameter(description = "The graph space name")
141153
@PathParam("graphspace") String graphSpace,
154+
@Parameter(description = "The belong id")
142155
@PathParam("id") String id) {
143156
LOG.debug("GraphSpace [{}] delete belong: {}", graphSpace, id);
144157

@@ -154,10 +167,13 @@ public void delete(@Context GraphManager manager,
154167
private static class JsonBelong implements Checkable {
155168

156169
@JsonProperty("user")
170+
@Schema(description = "The user id", required = true)
157171
private String user;
158172
@JsonProperty("group")
173+
@Schema(description = "The group id", required = true)
159174
private String group;
160175
@JsonProperty("belong_description")
176+
@Schema(description = "The belong description")
161177
private String description;
162178

163179
public HugeBelong build(HugeBelong belong) {

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
3535
import com.fasterxml.jackson.annotation.JsonProperty;
3636

37+
import io.swagger.v3.oas.annotations.Parameter;
38+
import io.swagger.v3.oas.annotations.media.Schema;
3739
import io.swagger.v3.oas.annotations.tags.Tag;
3840
import jakarta.annotation.security.RolesAllowed;
3941
import jakarta.inject.Singleton;
@@ -79,6 +81,7 @@ public String create(@Context GraphManager manager,
7981
@Produces(APPLICATION_JSON_WITH_CHARSET)
8082
@RolesAllowed({"admin"})
8183
public String update(@Context GraphManager manager,
84+
@Parameter(description = "The group id")
8285
@PathParam("id") String id,
8386
JsonGroup jsonGroup) {
8487
LOG.debug("update group: {}", jsonGroup);
@@ -100,6 +103,7 @@ public String update(@Context GraphManager manager,
100103
@Produces(APPLICATION_JSON_WITH_CHARSET)
101104
@RolesAllowed({"admin"})
102105
public String list(@Context GraphManager manager,
106+
@Parameter(description = "The limit of results to return")
103107
@QueryParam("limit") @DefaultValue("100") long limit) {
104108
LOG.debug("list groups");
105109

@@ -113,6 +117,7 @@ public String list(@Context GraphManager manager,
113117
@Produces(APPLICATION_JSON_WITH_CHARSET)
114118
@RolesAllowed({"admin"})
115119
public String get(@Context GraphManager manager,
120+
@Parameter(description = "The group id")
116121
@PathParam("id") String id) {
117122
LOG.debug("get group: {}", id);
118123

@@ -126,6 +131,7 @@ public String get(@Context GraphManager manager,
126131
@Consumes(APPLICATION_JSON)
127132
@RolesAllowed({"admin"})
128133
public void delete(@Context GraphManager manager,
134+
@Parameter(description = "The group id")
129135
@PathParam("id") String id) {
130136
LOG.debug("delete group: {}", id);
131137

@@ -141,8 +147,10 @@ public void delete(@Context GraphManager manager,
141147
private static class JsonGroup implements Checkable {
142148

143149
@JsonProperty("group_name")
150+
@Schema(description = "The group name", required = true)
144151
private String name;
145152
@JsonProperty("group_description")
153+
@Schema(description = "The group description")
146154
private String description;
147155

148156
public HugeGroup build(HugeGroup group) {

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
import com.fasterxml.jackson.annotation.JsonProperty;
3636
import com.google.common.collect.ImmutableMap;
3737

38+
import io.swagger.v3.oas.annotations.media.Schema;
3839
import io.swagger.v3.oas.annotations.tags.Tag;
3940
import jakarta.inject.Singleton;
4041
import jakarta.ws.rs.BadRequestException;
@@ -125,10 +126,13 @@ public String verifyToken(@Context GraphManager manager,
125126
private static class JsonLogin implements Checkable {
126127

127128
@JsonProperty("user_name")
129+
@Schema(description = "The user name")
128130
private String name;
129131
@JsonProperty("user_password")
132+
@Schema(description = "The user password")
130133
private String password;
131134
@JsonProperty("token_expire")
135+
@Schema(description = "Token expiration time in seconds")
132136
private long expire;
133137

134138
@Override

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@
3737
import com.fasterxml.jackson.annotation.JsonProperty;
3838
import com.google.common.collect.ImmutableMap;
3939

40+
import io.swagger.v3.oas.annotations.Parameter;
41+
import io.swagger.v3.oas.annotations.media.Schema;
4042
import io.swagger.v3.oas.annotations.tags.Tag;
4143
import jakarta.inject.Singleton;
4244
import jakarta.ws.rs.Consumes;
@@ -62,6 +64,7 @@ public class ManagerAPI extends API {
6264
@Consumes(APPLICATION_JSON)
6365
@Produces(APPLICATION_JSON_WITH_CHARSET)
6466
public String createManager(@Context GraphManager manager,
67+
@Parameter(description = "The graph space name")
6568
@PathParam("graphspace") String graphSpace,
6669
JsonManager jsonManager) {
6770
LOG.debug("Create manager: {}", jsonManager);
@@ -113,8 +116,11 @@ public String createManager(@Context GraphManager manager,
113116
@Timed
114117
@Consumes(APPLICATION_JSON)
115118
public void delete(@Context GraphManager manager,
119+
@Parameter(description = "The graph space name")
116120
@PathParam("graphspace") String graphSpace,
121+
@Parameter(description = "The user name")
117122
@QueryParam("user") String user,
123+
@Parameter(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN")
118124
@QueryParam("type") HugePermission type) {
119125
LOG.debug("Delete graph manager: {} {} {}", user, type, graphSpace);
120126
E.checkArgument(!"admin".equals(user) ||
@@ -157,7 +163,9 @@ public void delete(@Context GraphManager manager,
157163
@Timed
158164
@Consumes(APPLICATION_JSON)
159165
public String list(@Context GraphManager manager,
166+
@Parameter(description = "The graph space name")
160167
@PathParam("graphspace") String graphSpace,
168+
@Parameter(description = "The manager type: SPACE, SPACE_MEMBER or ADMIN")
161169
@QueryParam("type") HugePermission type) {
162170
LOG.debug("list graph manager: {} {}", type, graphSpace);
163171

@@ -187,7 +195,10 @@ public String list(@Context GraphManager manager,
187195
@Path("check")
188196
@Consumes(APPLICATION_JSON)
189197
public String checkRole(@Context GraphManager manager,
198+
@Parameter(description = "The graph space name")
190199
@PathParam("graphspace") String graphSpace,
200+
@Parameter(description = "The manager type: " +
201+
"SPACE, SPACE_MEMBER, or ADMIN")
191202
@QueryParam("type") HugePermission type) {
192203
LOG.debug("check if current user is graph manager: {} {}", type, graphSpace);
193204

@@ -219,8 +230,10 @@ public String checkRole(@Context GraphManager manager,
219230
@Path("role")
220231
@Consumes(APPLICATION_JSON)
221232
public String getRolesInGs(@Context GraphManager manager,
233+
@Parameter(description = "The graph space name")
222234
@PathParam("graphspace") String graphSpace,
223-
@QueryParam("user") String user) {
235+
@Parameter(description = "The user name") @QueryParam("user")
236+
String user) {
224237
LOG.debug("get user [{}]'s role in graph space [{}]", user, graphSpace);
225238
AuthManager authManager = manager.authManager();
226239
List<HugePermission> result = new ArrayList<>();
@@ -264,8 +277,10 @@ private void validGraphSpace(GraphManager manager, String graphSpace) {
264277
private static class JsonManager implements Checkable {
265278

266279
@JsonProperty("user")
280+
@Schema(description = "The user or group name", required = true)
267281
private String user;
268282
@JsonProperty("type")
283+
@Schema(description = "The manager type: SPACE, SPACE_MEMBER, or ADMIN", required = true)
269284
private HugePermission type;
270285

271286
@Override

‎hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ProjectAPI.java‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@
3939
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
4040
import com.fasterxml.jackson.annotation.JsonProperty;
4141

42+
import io.swagger.v3.oas.annotations.Parameter;
43+
import io.swagger.v3.oas.annotations.media.Schema;
4244
import io.swagger.v3.oas.annotations.tags.Tag;
4345
import jakarta.inject.Singleton;
4446
import jakarta.ws.rs.Consumes;
@@ -68,6 +70,7 @@ public class ProjectAPI extends API {
6870
@Consumes(APPLICATION_JSON)
6971
@Produces(APPLICATION_JSON_WITH_CHARSET)
7072
public String create(@Context GraphManager manager,
73+
@Parameter(description = "The graph space name")
7174
@PathParam("graphspace") String graphSpace,
7275
JsonProject jsonProject) {
7376
LOG.debug("GraphSpace [{}] create project: {}", graphSpace, jsonProject);
@@ -89,8 +92,15 @@ public String create(@Context GraphManager manager,
8992
@Consumes(APPLICATION_JSON)
9093
@Produces(APPLICATION_JSON_WITH_CHARSET)
9194
public String update(@Context GraphManager manager,
95+
@Parameter(description = "The graph space name")
9296
@PathParam("graphspace") String graphSpace,
97+
@Parameter(description = "The project id")
9398
@PathParam("id") String id,
99+
@Parameter(
100+
description = "The action to perform: " +
101+
"add_graph, remove_graph, " +
102+
"or empty for description " +
103+
"update")
94104
@QueryParam("action") String action,
95105
JsonProject jsonProject) {
96106
LOG.debug("GraphSpace [{}] update {} project: {}", graphSpace, action,
@@ -126,7 +136,9 @@ public String update(@Context GraphManager manager,
126136
@Timed
127137
@Produces(APPLICATION_JSON_WITH_CHARSET)
128138
public String list(@Context GraphManager manager,
139+
@Parameter(description = "The graph space name")
129140
@PathParam("graphspace") String graphSpace,
141+
@Parameter(description = "The limit of results to return")
130142
@QueryParam("limit") @DefaultValue("100") long limit) {
131143
LOG.debug("GraphSpace [{}] list project", graphSpace);
132144

@@ -140,7 +152,9 @@ public String list(@Context GraphManager manager,
140152
@Path("{id}")
141153
@Produces(APPLICATION_JSON_WITH_CHARSET)
142154
public String get(@Context GraphManager manager,
155+
@Parameter(description = "The graph space name")
143156
@PathParam("graphspace") String graphSpace,
157+
@Parameter(description = "The project id")
144158
@PathParam("id") String id) {
145159
LOG.debug("GraphSpace [{}] get project: {}", graphSpace, id);
146160

@@ -158,7 +172,9 @@ public String get(@Context GraphManager manager,
158172
@Path("{id}")
159173
@Consumes(APPLICATION_JSON)
160174
public void delete(@Context GraphManager manager,
175+
@Parameter(description = "The graph space name")
161176
@PathParam("graphspace") String graphSpace,
177+
@Parameter(description = "The project id")
162178
@PathParam("id") String id) {
163179
LOG.debug("GraphSpace [{}] delete project: {}", graphSpace, id);
164180

@@ -184,10 +200,13 @@ public static boolean isRemoveGraph(String action) {
184200
private static class JsonProject implements Checkable {
185201

186202
@JsonProperty("project_name")
203+
@Schema(description = "The project name", required = true)
187204
private String name;
188205
@JsonProperty("project_graphs")
206+
@Schema(description = "Set of graph names associated with the project")
189207
private Set<String> graphs;
190208
@JsonProperty("project_description")
209+
@Schema(description = "The project description")
191210
private String description;
192211

193212
public HugeProject build() {

0 commit comments

Comments
 (0)