refactor: add the desc of the vars in swagger-ui by lokidundun · Pull Request #2969 · apache/hugegraph

lokidundun · 2026-03-14T04:45:21Z

Purpose of the PR

close [Improve] Add the desc of the vars in swagger-ui #2335

Main Changes

Verifying these changes

Trivial rework / code cleanup without any test coverage. (No Need)
Already covered by existing tests, such as (please modify tests here).
Need tests and can be verified as follows:
- xxx

Does this PR potentially affect the following parts?

Dependencies (add/update license info & regenerate_known_dependencies.sh)
Modify configurations
The public API
Other affects (typed here)
Nope

Documentation Status

Doc - TODO
Doc - Done
Doc - No Need

imbajin · 2026-03-14T09:46:52Z

THX, style could ref https://github.com/apache/hugegraph/wiki/The-style-config-for-HugeGraph-in-IDEA

Copilot

Pull request overview

This PR addresses #2335 by enriching the OpenAPI/Swagger metadata so Swagger UI shows meaningful descriptions for API path/query parameters and request-body fields instead of repeating variable names.

Changes:

Add @Parameter descriptions to many REST endpoints’ path/query (and some body) parameters.
Add @Schema descriptions (and a few examples/required flags) to request/response model fields used by these endpoints.
Expand Swagger annotations across graph, schema, auth, job, traverser, and related APIs to improve Swagger UI documentation.

Reviewed changes

Copilot reviewed 56 out of 56 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/variables/VariablesAPI.java	Add parameter/body-field descriptions for variables endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/WeightedShortestPathAPI.java	Add Swagger descriptions for weighted-shortest-path query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/VerticesAPI.java	Add Swagger descriptions for traverser-vertices query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/Vertices.java	Add `@Schema` metadata for vertices request body fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/TraverserAPI.java	Add `@Schema` metadata for shared traverser request structures.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/TemplatePathsAPI.java	Import Swagger annotations (intended for improving TemplatePaths docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/SingleSourceShortestPathAPI.java	Import Swagger `@Parameter` (intended for improving API docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/ShortestPathAPI.java	Add Swagger descriptions for shortest-path query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/SameNeighborsAPI.java	Import Swagger annotations (intended for improving SameNeighbors docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/RingsAPI.java	Import Swagger `@Parameter` (intended for improving Rings docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/ResourceAllocationAPI.java	Import Swagger `@Parameter` (intended for improving ResourceAllocation docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/RaysAPI.java	Import Swagger `@Parameter` (intended for improving Rays docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/PersonalRankAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/PathsAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/NeighborRankAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/MultiNodeShortestPathAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KoutAPI.java	Add Swagger descriptions for k-out query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KneighborAPI.java	Add Swagger descriptions for k-neighbor query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/JaccardSimilarityAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/FusiformSimilarityAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgesAPI.java	Add Swagger description for `split_size` shards query param.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgeExistenceAPI.java	Import Swagger `@Parameter` (intended for improving EdgeExistence docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CustomizedPathsAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CustomizedCrosspointsAPI.java	Import Swagger annotations for request/parameter documentation.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CrosspointsAPI.java	Import Swagger `@Parameter` (intended for improving Crosspoints docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CountAPI.java	Add Swagger descriptions for count endpoint params and request body fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AllShortestPathsAPI.java	Add Swagger descriptions for all-shortest-paths query/path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AdamicAdarAPI.java	Import Swagger `@Parameter` (intended for improving AdamicAdar docs).
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/GraphSpaceAPI.java	Add Swagger descriptions for graph-space endpoints and request models.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/VertexLabelAPI.java	Add Swagger descriptions for vertex-label endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/PropertyKeyAPI.java	Add Swagger descriptions for property-key endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java	Add Swagger descriptions for index-label endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/EdgeLabelAPI.java	Add Swagger descriptions for edge-label endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/raft/RaftAPI.java	Add Swagger descriptions for raft management endpoint parameters.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java	Add Swagger description for `status` query param.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java	Add Swagger descriptions for graph-profile management endpoint parameters.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java	Add Swagger descriptions for metrics output `type` parameter.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/TaskAPI.java	Add Swagger descriptions for task query/path params and pagination params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/RebuildAPI.java	Add Swagger descriptions for rebuild endpoint path params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/GremlinAPI.java	Add Swagger descriptions for Gremlin job request params and request fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/ComputerAPI.java	Add Swagger descriptions for computer-job endpoint params and body.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java	Add Swagger descriptions for algorithm-job endpoint params and body.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/gremlin/GremlinAPI.java	Add Swagger description for Gremlin query request body parameter.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java	Add Swagger descriptions for vertex CRUD/list parameters and batch request fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/EdgeAPI.java	Add Swagger descriptions for edge CRUD/list parameters and batch request fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/BatchAPI.java	Add `@Schema` metadata for shared batch element fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherModel.java	Add `@Schema` metadata to Cypher response model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java	Add Swagger descriptions for cypher endpoint parameters/body.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/UserAPI.java	Add Swagger descriptions for auth user endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/TargetAPI.java	Add Swagger descriptions for auth target endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ProjectAPI.java	Add Swagger descriptions for auth project endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java	Add Swagger descriptions for manager endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java	Add `@Schema` metadata for login request fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java	Add Swagger descriptions for group endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java	Add Swagger descriptions for belong endpoints and request model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java	Add Swagger descriptions for access endpoints and request model fields.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

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

+                         @Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
+                         @Parameter(description = "The project id") @PathParam("id") String id,
+                         @Parameter(description = "The action to perform: add_graph, remove_graph, or empty for description update") @QueryParam("action") String action,


...server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/SameNeighborsAPI.java

+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.tags.Tag;


...ver/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AllShortestPathsAPI.java

+                      @Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
+                      @Parameter(description = "The graph name") @PathParam("graph") String graph,
+                      @Parameter(description = "The source vertex ID") @QueryParam("source") String source,
+                      @Parameter(description = "The target vertex ID") @QueryParam("target") String target,


hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgesAPI.java

                         @PathParam("graphspace") String graphSpace,
                         @PathParam("graph") String graph,
-                         @QueryParam("split_size") long splitSize) {
+                         @Parameter(description = "The split size for shards") @QueryParam("split_size") long splitSize) {


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

    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");


...graph-api/src/main/java/org/apache/hugegraph/api/traversers/SingleSourceShortestPathAPI.java

+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;


...ph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AdamicAdarAPI.java

 import com.codahale.metrics.annotation.Timed;
 import com.google.common.collect.ImmutableMap;

+import io.swagger.v3.oas.annotations.Parameter;


...server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgeExistenceAPI.java

+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;


...hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/WeightedShortestPathAPI.java

+                      @Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
+                      @Parameter(description = "The graph name") @PathParam("graph") String graph,
+                      @Parameter(description = "The source vertex ID") @QueryParam("source") String source,
+                      @Parameter(description = "The target vertex ID") @QueryParam("target") String target,


...raph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/VerticesAPI.java

+                       @Parameter(description = "The graph space name") @PathParam("graphspace") String graphSpace,
+                       @Parameter(description = "The graph name") @PathParam("graph") String graph,
+                       @Parameter(description = "The vertex IDs") @QueryParam("ids") List<String> stringIds) {


lokidundun · 2026-03-14T10:08:53Z

THX, style could ref https://github.com/apache/hugegraph/wiki/The-style-config-for-HugeGraph-in-IDEA

Thanks for the guide! I'll refer to this style config in IDEA to keep my code consistent with the project's standards.

Copilot

Pull request overview

This PR addresses #2335 by enriching HugeGraph Server’s REST API Swagger/OpenAPI metadata so Swagger-UI displays meaningful descriptions for path/query parameters and request/response models instead of repeating variable names.

Changes:

Add @Parameter descriptions to many JAX-RS resource method parameters (path/query/body).
Add @Schema metadata to request/response DTOs and inner request classes used by APIs.
Improve Swagger-UI usability for schema, traverser, auth, job, metrics, raft, cypher, and variables endpoints.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/variables/VariablesAPI.java	Adds parameter and body field descriptions for variables endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/WeightedShortestPathAPI.java	Adds query/path parameter descriptions for weighted shortest path.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/VerticesAPI.java	Adds path/query parameter descriptions for traverser vertices lookup.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/Vertices.java	Adds schema descriptions/examples for traverser vertices request model.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/TraverserAPI.java	Adds schema descriptions for traversal step request models.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/ShortestPathAPI.java	Adds query/path parameter descriptions for shortest path.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KoutAPI.java	Adds query/path parameter descriptions for k-out traverser.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KneighborAPI.java	Adds query/path parameter descriptions for k-neighbor traverser.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgesAPI.java	Adds query parameter description for shards split size.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CountAPI.java	Adds parameter + schema descriptions for count request model and endpoint params.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AllShortestPathsAPI.java	Adds query/path parameter descriptions for all-shortest-paths traverser.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/GraphSpaceAPI.java	Adds parameter and schema descriptions for graph-space operations and DTOs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/VertexLabelAPI.java	Adds parameter + request schema descriptions for vertex-label APIs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/PropertyKeyAPI.java	Adds parameter + request schema descriptions for property-key APIs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java	Adds parameter + request schema descriptions for index-label APIs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/EdgeLabelAPI.java	Adds parameter + request schema descriptions for edge-label APIs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/raft/RaftAPI.java	Adds query/path parameter descriptions for raft peer/leader operations.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java	Adds query parameter description for enable/disable switch.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java	Adds parameter descriptions for graph management endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java	Adds query parameter description for output format selection.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/TaskAPI.java	Adds query/path parameter descriptions for task listing and task operations.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/RebuildAPI.java	Adds path parameter descriptions for rebuild endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/GremlinAPI.java	Adds request body parameter description and request schema annotations for gremlin jobs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/ComputerAPI.java	Adds path/body parameter descriptions for computer jobs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java	Adds path/body parameter descriptions for algorithm jobs.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/gremlin/GremlinAPI.java	Adds request body parameter description for gremlin query endpoint.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java	Adds parameter + request schema descriptions for vertex CRUD and batch operations.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/EdgeAPI.java	Adds parameter + request schema descriptions for edge CRUD and batch operations.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/BatchAPI.java	Adds schema descriptions for shared batch element model fields.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherModel.java	Adds schema descriptions for cypher response model.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java	Adds path/query/body parameter descriptions for cypher query endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/UserAPI.java	Adds parameter + request schema descriptions for auth user endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/TargetAPI.java	Adds parameter + request schema descriptions for auth target endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ProjectAPI.java	Adds parameter + request schema descriptions for auth project endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java	Adds parameter + request schema descriptions for auth manager endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java	Adds request schema descriptions for login request model.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java	Adds parameter + request schema descriptions for auth group endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java	Adds parameter + request schema descriptions for belong endpoints.
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java	Adds parameter + request schema descriptions for access endpoints.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java

                     @PathParam("graphspace") String graphSpace,
+                     @Parameter(description = "The graph name")
                     @PathParam("name") String name,
+                     @Parameter(description = "Confirmation message to drop the graph, must be: " + CONFIRM_DROP)


hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java

                         @PathParam("name") String name,
+                         @Parameter(description = "The graph name to clone from (optional)")
                         @QueryParam("clone_graph_name") String clone,
+                         @Parameter(description = "The graph configuration options including 'backend', 'serializer', 'store', and optionally 'description'")


...graph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/PropertyKeyAPI.java

+                         @Parameter(description = "Action to perform: 'append' to add new properties, " +
+                                                  "'remove' to delete existing properties, " +
+                                                  "'clear' to clear OLAP property data")


Copilot

Pull request overview

This PR enhances the HugeGraph Server REST OpenAPI/Swagger output by adding human-readable descriptions for path/query/body fields so Swagger UI no longer shows parameter names as the only “description”.

Changes:

Added @Parameter descriptions to many REST endpoints for path/query/body parameters.
Added @Schema metadata (descriptions/examples/required flags) to multiple request/response DTOs.
Minor formatting adjustments to keep method signatures/readability consistent with the added annotations.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/variables/VariablesAPI.java	Add Swagger parameter + schema descriptions for variable endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/WeightedShortestPathAPI.java	Add Swagger descriptions for weighted shortest path query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/VerticesAPI.java	Add Swagger descriptions for vertex IDs query
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/Vertices.java	Add `@Schema` descriptions/examples for Vertices DTO fields
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/TraverserAPI.java	Add `@Schema` descriptions for shared traverser DTOs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/ShortestPathAPI.java	Add Swagger descriptions for shortest path query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KoutAPI.java	Add Swagger descriptions for kout query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KneighborAPI.java	Add Swagger descriptions for kneighbor query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgesAPI.java	Add Swagger description for shards split_size param
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CountAPI.java	Add Swagger param + schema descriptions for count traverser
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AllShortestPathsAPI.java	Add Swagger descriptions for all-shortest-paths query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/GraphSpaceAPI.java	Add Swagger descriptions for graphspace operations + DTO fields
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/VertexLabelAPI.java	Add Swagger descriptions for vertex-label endpoints + request DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/PropertyKeyAPI.java	Add Swagger descriptions for property-key endpoints + request DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java	Add Swagger descriptions for index-label endpoints + request DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/EdgeLabelAPI.java	Add Swagger descriptions for edge-label endpoints + request DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/raft/RaftAPI.java	Add Swagger descriptions for raft management endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java	Add Swagger description for status toggle query param
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java	Add Swagger descriptions for graph profile endpoints and bodies
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java	Add Swagger descriptions for metrics output format param
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/TaskAPI.java	Add Swagger descriptions for task list/get/delete/update params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/RebuildAPI.java	Add Swagger descriptions for rebuild endpoint path params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/GremlinAPI.java	Add Swagger descriptions for gremlin job request + DTO schema
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/ComputerAPI.java	Add Swagger descriptions for computer job endpoint params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java	Add Swagger descriptions for algorithm job endpoint params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/gremlin/GremlinAPI.java	Add Swagger description for gremlin query request body
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java	Add Swagger descriptions for vertex endpoints + batch request schema
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/EdgeAPI.java	Add Swagger descriptions for edge endpoints + batch request schema
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/BatchAPI.java	Add shared `@Schema` metadata for batch element base DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherModel.java	Add `@Schema` descriptions for Cypher response model fields
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java	Add Swagger descriptions for cypher params/body
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/UserAPI.java	Add Swagger param + schema descriptions for user auth endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/TargetAPI.java	Add Swagger param + schema descriptions for target endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ProjectAPI.java	Add Swagger param + schema descriptions for project endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java	Add Swagger param + schema descriptions for manager endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java	Add `@Schema` descriptions to login request DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java	Add Swagger param + schema descriptions for group endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java	Add Swagger param + schema descriptions for belong endpoints/DTO
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java	Add Swagger param + schema descriptions for access endpoints/DTO

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java

+                       @Parameter(description = "Filter by vertex label")
                       @QueryParam("label") String label,
+                       @Parameter(description = "Filter by vertex properties in JSON format, " +
+                                                "e.g., {\"key1\": \"value1\", \"key2\": \"value2\"}")


Copilot

Pull request overview

This PR addresses #2335 by enriching the generated OpenAPI/Swagger documentation so Swagger UI shows meaningful descriptions for path/query parameters and request-body fields instead of only variable names.

Changes:

Add @Parameter(description=...) to many REST endpoints’ @PathParam / @QueryParam arguments.
Add @Schema(description=..., required=...) to multiple request/response model fields used by those endpoints.
Minor formatting adjustments while inserting the annotations.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/variables/VariablesAPI.java	Adds parameter + body-field schema descriptions for variables endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/WeightedShortestPathAPI.java	Adds Swagger parameter descriptions for weighted shortest path query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/VerticesAPI.java	Adds Swagger parameter descriptions for vertices-by-ids endpoint
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/Vertices.java	Adds schema descriptions/examples for vertices request model fields
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/TraverserAPI.java	Adds schema descriptions for traverser step models
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/ShortestPathAPI.java	Adds Swagger parameter descriptions for shortest path query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KoutAPI.java	Adds Swagger parameter descriptions for k-out query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/KneighborAPI.java	Adds Swagger parameter descriptions for k-neighbor query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/EdgesAPI.java	Adds Swagger parameter description for shards split_size
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/CountAPI.java	Adds parameter + request-body schema descriptions for count traverser
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/traversers/AllShortestPathsAPI.java	Adds Swagger parameter descriptions for all-shortest-paths query params
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/space/GraphSpaceAPI.java	Adds parameter + request-body schema descriptions for graph space APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/VertexLabelAPI.java	Adds Swagger parameter + schema descriptions for vertex label APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/PropertyKeyAPI.java	Adds Swagger parameter + schema descriptions for property key APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/IndexLabelAPI.java	Adds Swagger parameter + schema descriptions for index label APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/schema/EdgeLabelAPI.java	Adds Swagger parameter + schema descriptions for edge label APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/raft/RaftAPI.java	Adds Swagger parameter descriptions for raft management endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/WhiteIpListAPI.java	Adds Swagger parameter description for status toggle
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java	Adds Swagger parameter descriptions for graph profile/management endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java	Adds Swagger parameter descriptions for metrics output format
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/TaskAPI.java	Adds Swagger parameter descriptions for task list/get/delete/update
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/RebuildAPI.java	Adds Swagger parameter descriptions for rebuild endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/GremlinAPI.java	Adds parameter + schema descriptions for gremlin job request
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/ComputerAPI.java	Adds Swagger parameter descriptions for computer job endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/job/AlgorithmAPI.java	Adds Swagger parameter descriptions for algorithm job endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/gremlin/GremlinAPI.java	Adds Swagger parameter description for gremlin request body
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/VertexAPI.java	Adds Swagger parameter + schema descriptions for vertex CRUD/batch
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/EdgeAPI.java	Adds Swagger parameter + schema descriptions for edge CRUD/batch
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/graph/BatchAPI.java	Adds schema descriptions for shared batch element model
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherModel.java	Adds schema descriptions for cypher response model
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/cypher/CypherAPI.java	Adds Swagger parameter descriptions for cypher endpoints
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/UserAPI.java	Adds Swagger parameter + schema descriptions for user APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/TargetAPI.java	Adds Swagger parameter + schema descriptions for target APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ProjectAPI.java	Adds Swagger parameter + schema descriptions for project APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/ManagerAPI.java	Adds Swagger parameter + schema descriptions for manager APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/LoginAPI.java	Adds schema descriptions for login request model
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/GroupAPI.java	Adds Swagger parameter + schema descriptions for group APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/BelongAPI.java	Adds Swagger parameter + schema descriptions for belong APIs
hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/auth/AccessAPI.java	Adds Swagger parameter + schema descriptions for access APIs

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/metrics/MetricsAPI.java

+    public String statistics(@Parameter(description = "Output format type: 'json' for JSON format, " +
+                                               "other values for Prometheus format")
+                             @QueryParam("type") String type) {


hugegraph-server/hugegraph-api/src/main/java/org/apache/hugegraph/api/profile/GraphsAPI.java

+                                 description = "The action map containing 'action' key with value" +
+                                               " 'reload'")


imbajin

Thanks for your contribution & quick resp, LGTM now

lokidundun added 2 commits March 14, 2026 12:22

add: add des for var

b367e01

remove unuse file

c6e4b79

imbajin requested a review from Copilot March 14, 2026 09:45

Copilot started reviewing on behalf of imbajin March 14, 2026 09:45 View session

imbajin changed the title ~~Improve: Add the desc of the vars in swagger-ui~~ refactor: add the desc of the vars in swagger-ui Mar 14, 2026

Copilot AI reviewed Mar 14, 2026

View reviewed changes

lokidundun added 2 commits March 14, 2026 21:56

optimize: formate the code style

94609b6

optimize: formate the code style

b5609ab

imbajin requested a review from Copilot March 15, 2026 13:25

Copilot started reviewing on behalf of imbajin March 15, 2026 13:26 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

optimize: format the code style

3b8d349

imbajin requested a review from Copilot March 15, 2026 14:13

Copilot started reviewing on behalf of imbajin March 15, 2026 14:14 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

optimize: format the code style

d21ccae

imbajin requested a review from Copilot March 16, 2026 04:36

Copilot started reviewing on behalf of imbajin March 16, 2026 04:37 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

lokidundun added 2 commits March 16, 2026 13:43

optimize: change some des

931e905

optimize: decline some des

3230fb1

imbajin approved these changes Mar 16, 2026

View reviewed changes

imbajin merged commit 5578b79 into apache:master Mar 16, 2026
13 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

refactor: add the desc of the vars in swagger-ui#2969
imbajin merged 8 commits intoapache:masterfrom
lokidundun:add-des

lokidundun commented Mar 14, 2026

Uh oh!

imbajin commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

lokidundun commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

imbajin left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		import io.swagger.v3.oas.annotations.Parameter;
		import io.swagger.v3.oas.annotations.tags.Tag;

		description = "The action map containing 'action' key with value" +
		" 'reload'")

Conversation

lokidundun commented Mar 14, 2026

Purpose of the PR

Main Changes

Verifying these changes

Does this PR potentially affect the following parts?

Documentation Status

Uh oh!

imbajin commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

lokidundun commented Mar 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

imbajin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants