This is an automated email from the ASF dual-hosted git repository.
mpochatkin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new 022ca06833 IGNITE-23219 Fix REST API description (#4405)
022ca06833 is described below
commit 022ca06833c998465b20c959c30612a3c76ca86b
Author: Vadim Pakhnushev <[email protected]>
AuthorDate: Tue Sep 17 13:42:38 2024 +0300
IGNITE-23219 Fix REST API description (#4405)
---
.../rest/api/cluster/ClusterManagementApi.java | 4 +--
.../internal/rest/api/cluster/TopologyApi.java | 12 +++++++--
.../internal/rest/api/compute/ComputeApi.java | 14 +++++-----
.../api/configuration/ClusterConfigurationApi.java | 20 +++++++++++----
.../api/configuration/NodeConfigurationApi.java | 20 +++++++++++----
.../rest/api/deployment/DeploymentCodeApi.java | 30 +++++++++++++++++-----
.../internal/rest/api/metric/NodeMetricApi.java | 12 ++++++---
.../internal/rest/api/node/NodeManagementApi.java | 12 ++++++---
.../ignite/internal/rest/api/node/NodeState.java | 2 +-
.../ignite/internal/rest/api/node/State.java | 2 +-
10 files changed, 90 insertions(+), 38 deletions(-)
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java
index 665a15515e..8ab84e363b 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterManagementApi.java
@@ -42,7 +42,7 @@ public interface ClusterManagementApi {
* Returns cluster state.
*/
@Get("state")
- @Operation(operationId = "clusterState", description = "Returns current
cluster status.")
+ @Operation(operationId = "clusterState", summary = "Get cluster state",
description = "Returns current cluster status.")
@ApiResponse(responseCode = "200", description = "Cluster status
returned.",
content = @Content(mediaType = MediaType.APPLICATION_JSON, schema
= @Schema(implementation = ClusterState.class)))
@ApiResponse(responseCode = "404", description = "Cluster status not
found. Most likely, the cluster is not initialized.",
@@ -57,7 +57,7 @@ public interface ClusterManagementApi {
* @return Completable future that will be completed when cluster is
initialized.
*/
@Post("init")
- @Operation(operationId = "init", description = "Initializes a new
cluster.")
+ @Operation(operationId = "init", summary = "Initialize cluster",
description = "Initialize a new cluster.")
@ApiResponse(responseCode = "200", description = "Cluster initialized.")
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/TopologyApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/TopologyApi.java
index b324c16710..70e1ec7b6c 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/TopologyApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/TopologyApi.java
@@ -40,7 +40,11 @@ public interface TopologyApi {
* Cluster physical topology.
*/
@Get("physical")
- @Operation(operationId = "physical", description = "Gets information about
physical cluster topology.")
+ @Operation(
+ operationId = "physical",
+ summary = "Get physical topology",
+ description = "Gets information about physical cluster topology."
+ )
@ApiResponse(responseCode = "200", description = "Physical topology
returned.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
array = @ArraySchema(schema = @Schema(implementation =
ClusterNode.class))))
@@ -52,7 +56,11 @@ public interface TopologyApi {
* Cluster logical topology.
*/
@Get("logical")
- @Operation(operationId = "logical", description = "Gets information about
logical cluster topology.")
+ @Operation(
+ operationId = "logical",
+ summary = "Get logical topology",
+ description = "Gets information about logical cluster topology."
+ )
@ApiResponse(responseCode = "200", description = "Logical topology
returned.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
array = @ArraySchema(schema = @Schema(implementation =
ClusterNode.class))))
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/compute/ComputeApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/compute/ComputeApi.java
index 704a283c1b..17a39d881b 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/compute/ComputeApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/compute/ComputeApi.java
@@ -50,7 +50,7 @@ public interface ComputeApi {
@Operation(summary = "Retrieve all job states", description = "Fetches the
current states of all compute jobs.")
@ApiResponse(
responseCode = "200",
- description = "Successful retrieval of job states.",
+ description = "Successfully retrieved job states.",
content = @Content(mediaType = APPLICATION_JSON, array =
@ArraySchema(schema = @Schema(implementation = JobState.class)))
)
@Get("jobs")
@@ -62,10 +62,10 @@ public interface ComputeApi {
* @param jobId The unique identifier of the compute job.
* @return The state of the specified compute job.
*/
- @Operation(summary = "Retrieve a job state", description = "Fetches the
current state of a specific compute job identified by jobId.")
+ @Operation(summary = "Retrieve job state", description = "Fetches the
current state of a specific compute job identified by jobId.")
@ApiResponse(
responseCode = "200",
- description = "Successful retrieval of the job state.",
+ description = "Successfully retrieved the job state.",
content = @Content(mediaType = APPLICATION_JSON, schema =
@Schema(implementation = JobState.class))
)
@ApiResponse(
@@ -85,10 +85,10 @@ public interface ComputeApi {
* @param updateJobPriorityBody The new priority data for the job.
* @return The result of the operation.
*/
- @Operation(summary = "Update a job's priority", description = "Updates the
priority of a specific compute job identified by jobId.")
+ @Operation(summary = "Update job priority", description = "Updates the
priority of a specific compute job identified by jobId.")
@ApiResponse(
responseCode = "200",
- description = "Successful update of the job priority.",
+ description = "Successfully updated job priority.",
content = @Content(mediaType = APPLICATION_JSON)
)
@ApiResponse(
@@ -113,10 +113,10 @@ public interface ComputeApi {
* @param jobId The unique identifier of the compute job.
* @return The result of the cancellation operation.
*/
- @Operation(summary = "Cancel a job", description = "Cancels a specific
compute job identified by jobId.")
+ @Operation(summary = "Cancel job", description = "Cancels a specific
compute job identified by jobId.")
@ApiResponse(
responseCode = "200",
- description = "Successful cancellation of the job.",
+ description = "Successfully cancelled the job.",
content = @Content(mediaType = APPLICATION_JSON)
)
@ApiResponse(
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/ClusterConfigurationApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/ClusterConfigurationApi.java
index a19641691b..be4f8c6ca4 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/ClusterConfigurationApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/ClusterConfigurationApi.java
@@ -46,7 +46,11 @@ public interface ClusterConfigurationApi {
*
* @return the whole cluster configuration in HOCON format.
*/
- @Operation(operationId = "getClusterConfiguration", description = "Gets
the current configuration of the cluster.")
+ @Operation(
+ operationId = "getClusterConfiguration",
+ summary = "Get cluster configuration",
+ description = "Gets the current configuration of the cluster. The
configuration is returned in HOCON format."
+ )
@ApiResponse(
responseCode = "200", description = "Received cluster
configuration.",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")))
@@ -65,8 +69,11 @@ public interface ClusterConfigurationApi {
*
* @param updatedConfiguration the cluster configuration to update.
*/
- @Operation(operationId = "updateClusterConfiguration", description =
"Updates cluster configuration. "
- + "New configuration should be provided in HOCON format.")
+ @Operation(
+ operationId = "updateClusterConfiguration",
+ summary = "Update cluster configuration",
+ description = "Updates cluster configuration. New configuration
should be provided in HOCON format."
+ )
@ApiResponse(responseCode = "200", description = "Configuration updated.")
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@@ -87,8 +94,11 @@ public interface ClusterConfigurationApi {
* @param path to represent a cluster configuration.
* @return system configuration in HOCON format represented by given path.
*/
- @Operation(operationId = "getClusterConfigurationByPath",
- description = "Gets the configuration on the specific path.
Configuration is in HOCON format")
+ @Operation(
+ operationId = "getClusterConfigurationByPath",
+ summary = "Get configuration represented by path",
+ description = "Gets the configuration on the specific path.
Configuration is in HOCON format"
+ )
@ApiResponse(responseCode = "200", description = "Configuration of the
cluster on the specified path.",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")))
@ApiResponse(responseCode = "500", description = "Internal error.",
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/NodeConfigurationApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/NodeConfigurationApi.java
index 28dfd3dea7..732c688d72 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/NodeConfigurationApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/NodeConfigurationApi.java
@@ -46,7 +46,11 @@ public interface NodeConfigurationApi {
*
* @return the whole node configuration in HOCON format.
*/
- @Operation(operationId = "getNodeConfiguration", description = "Gets node
configuration in HOCON format.")
+ @Operation(
+ operationId = "getNodeConfiguration",
+ summary = "Get node configuration",
+ description = "Gets node configuration in HOCON format."
+ )
@ApiResponse(responseCode = "200", description = "Full node
configuration.",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")))
@ApiResponse(responseCode = "500", description = "Internal error.",
@@ -63,8 +67,11 @@ public interface NodeConfigurationApi {
* @param path to represent a node configuration.
* @return system configuration in HOCON format represented by given path.
*/
- @Operation(operationId = "getNodeConfigurationByPath",
- description = "Gets a configuration of a specific node, in HOCON
format.")
+ @Operation(
+ operationId = "getNodeConfigurationByPath",
+ summary = "Get configuration represented by path",
+ description = "Gets a configuration of a specific node, in HOCON
format."
+ )
@ApiResponse(responseCode = "200",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")),
description = "Returned node configuration.")
@@ -82,8 +89,11 @@ public interface NodeConfigurationApi {
*
* @param updatedConfiguration the node configuration to update. This is
represented as a plain text.
*/
- @Operation(operationId = "updateNodeConfiguration", description = "Updates
node configuration. "
- + "New configuration should be provided in HOCON format.")
+ @Operation(
+ operationId = "updateNodeConfiguration",
+ summary = "Update node configuration",
+ description = "Updates node configuration. New configuration
should be provided in HOCON format."
+ )
@ApiResponse(responseCode = "200", description = "Configuration
successfully updated.")
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/deployment/DeploymentCodeApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/deployment/DeploymentCodeApi.java
index 176473ef24..a903ba6b91 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/deployment/DeploymentCodeApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/deployment/DeploymentCodeApi.java
@@ -53,7 +53,7 @@ public interface DeploymentCodeApi {
/**
* Deploy unit REST method.
*/
- @Operation(operationId = "deployUnit", description = "Deploys provided
unit to the cluster.")
+ @Operation(operationId = "deployUnit", summary = "Deploy unit",
description = "Deploys provided unit to the cluster.")
@ApiResponse(responseCode = "200", description = "Unit deployed
successfully.",
content = @Content(mediaType = APPLICATION_JSON, schema =
@Schema(type = "boolean"))
)
@@ -83,7 +83,11 @@ public interface DeploymentCodeApi {
/**
* Undeploy unit REST method.
*/
- @Operation(operationId = "undeployUnit", description = "Undeploys the unit
with provided unitId and unitVersion.")
+ @Operation(
+ operationId = "undeployUnit",
+ summary = "Undeploy unit",
+ description = "Undeploys the unit with provided unitId and
unitVersion."
+ )
@ApiResponse(responseCode = "200", description = "Unit undeployed
successfully.")
@ApiResponse(responseCode = "404",
description = "Unit with provided identifier and version does not
exist.",
@@ -104,7 +108,7 @@ public interface DeploymentCodeApi {
/**
* Cluster unit statuses REST method.
*/
- @Operation(operationId = "listClusterStatuses", description = "Cluster
unit statuses.")
+ @Operation(operationId = "listClusterStatuses", summary = "Get cluster
unit statuses", description = "Cluster unit statuses.")
@ApiResponse(responseCode = "200",
description = "All statuses returned successfully.",
content = @Content(mediaType = APPLICATION_JSON, array =
@ArraySchema(schema = @Schema(implementation = UnitStatus.class)))
@@ -122,7 +126,11 @@ public interface DeploymentCodeApi {
/**
* Cluster unit statuses REST method.
*/
- @Operation(operationId = "listClusterStatusesByUnit", description =
"Cluster unit statuses.")
+ @Operation(
+ operationId = "listClusterStatusesByUnit",
+ summary = "Get specific cluster unit statuses",
+ description = "Cluster unit statuses by unit."
+ )
@ApiResponse(responseCode = "200",
description = "All statuses returned successfully.",
content = @Content(mediaType = APPLICATION_JSON, array =
@ArraySchema(schema = @Schema(implementation = UnitStatus.class)))
@@ -144,9 +152,13 @@ public interface DeploymentCodeApi {
/**
* Node unit statuses REST method.
*/
- @Operation(operationId = "listNodeStatuses", description = "Node unit
statuses.")
+ @Operation(
+ operationId = "listNodeStatuses",
+ summary = "Get node unit statuses",
+ description = "Returns a list of unit statuses per node."
+ )
@ApiResponse(responseCode = "200",
- description = "All statuses returned successfully.",
+ description = "All statuses were returned successfully.",
content = @Content(mediaType = APPLICATION_JSON, array =
@ArraySchema(schema = @Schema(implementation = UnitStatus.class)))
)
@ApiResponse(responseCode = "500",
@@ -162,7 +174,11 @@ public interface DeploymentCodeApi {
/**
* Node unit statuses REST method.
*/
- @Operation(operationId = "listNodeStatusesByUnit", description = "Node
unit statuses.")
+ @Operation(
+ operationId = "listNodeStatusesByUnit",
+ summary = "Get specific node unit statuses",
+ description = "Returns a list of node unit statuses by unit."
+ )
@ApiResponse(responseCode = "200",
description = "All statuses returned successfully.",
content = @Content(mediaType = APPLICATION_JSON, array =
@ArraySchema(schema = @Schema(implementation = UnitStatus.class)))
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/NodeMetricApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/NodeMetricApi.java
index e21fffe2ae..7a64a965e6 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/NodeMetricApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/NodeMetricApi.java
@@ -39,7 +39,7 @@ import org.apache.ignite.internal.rest.constants.MediaType;
public interface NodeMetricApi {
/** Enable metric source. */
- @Operation(operationId = "enableNodeMetric", description = "Enables the
specified metric source.")
+ @Operation(operationId = "enableNodeMetric", summary = "Enable metric
source", description = "Enables the specified metric source.")
@ApiResponse(responseCode = "200", description = "Metric source enabled.")
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@@ -51,7 +51,7 @@ public interface NodeMetricApi {
void enable(@Body String srcName);
/** Disable metric source. */
- @Operation(operationId = "disableNodeMetric", description = "Disables the
specified metric source.")
+ @Operation(operationId = "disableNodeMetric", summary = "Disable metric
source", description = "Disables the specified metric source.")
@ApiResponse(responseCode = "200", description = "Metric source disabled.")
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@@ -63,7 +63,11 @@ public interface NodeMetricApi {
void disable(@Body String srcName);
/** List metric sources. */
- @Operation(operationId = "listNodeMetricSources", description = "Gets a
list of all available metric sources.")
+ @Operation(
+ operationId = "listNodeMetricSources",
+ summary = "List metric sources",
+ description = "Gets a list of all available metric sources."
+ )
@ApiResponse(responseCode = "200", description = "Returned a list of
metric sources.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
array = @ArraySchema(schema = @Schema(implementation =
MetricSource.class))))
@@ -73,7 +77,7 @@ public interface NodeMetricApi {
Collection<MetricSource> listMetricSources();
/** List metric sets. */
- @Operation(operationId = "listNodeMetricSets", description = "Gets a list
of all enabled metric sets.")
+ @Operation(operationId = "listNodeMetricSets", summary = "List metric
sets", description = "Gets a list of all enabled metric sets.")
@ApiResponse(responseCode = "200", description = "Returned a list of
metric sets.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
array = @ArraySchema(schema = @Schema(implementation =
MetricSet.class))))
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeManagementApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeManagementApi.java
index da8d7db0d4..e0f692e2ba 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeManagementApi.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeManagementApi.java
@@ -37,9 +37,9 @@ import org.apache.ignite.internal.rest.constants.MediaType;
public interface NodeManagementApi {
@Get("state")
- @Operation(operationId = "nodeState", description = "Gets current network
status.")
+ @Operation(operationId = "nodeState", summary = "Get node state",
description = "Gets node state.")
@ApiResponses({
- @ApiResponse(responseCode = "200", description = "Current node
status.",
+ @ApiResponse(responseCode = "200", description = "Node state.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = NodeState.class))),
@ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON,
schema = @Schema(implementation = Problem.class)))
@@ -47,7 +47,7 @@ public interface NodeManagementApi {
NodeState state();
@Get("info")
- @Operation(operationId = "nodeInfo", description = "Gets node info.")
+ @Operation(operationId = "nodeInfo", summary = "Get node information",
description = "Gets information about the node.")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "Node info.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = NodeInfo.class))),
@@ -57,7 +57,11 @@ public interface NodeManagementApi {
NodeInfo info();
@Get("version")
- @Operation(operationId = "nodeVersion", description = "Gets the version of
Apache Ignite the node uses.")
+ @Operation(
+ operationId = "nodeVersion",
+ summary = "Get application version on node",
+ description = "Gets the version of Apache Ignite the node uses."
+ )
@ApiResponse(responseCode = "200", description = "Node version.",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")))
@ApiResponse(responseCode = "500", description = "Internal error",
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeState.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeState.java
index d55c78cce0..f5e843f9cb 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeState.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeState.java
@@ -31,7 +31,7 @@ public class NodeState {
@Schema(description = "Unique node name.", requiredMode =
RequiredMode.REQUIRED)
private final String name;
- @Schema(description = "Node status.", requiredMode = RequiredMode.REQUIRED)
+ @Schema(description = "Node state.", requiredMode = RequiredMode.REQUIRED)
private final State state;
/**
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/State.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/State.java
index b0cc307d56..4f887f237a 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/State.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/State.java
@@ -20,7 +20,7 @@ package org.apache.ignite.internal.rest.api.node;
import io.swagger.v3.oas.annotations.media.Schema;
/** Node state. */
-@Schema(description = "Possible node statuses.")
+@Schema(description = "Possible node states.")
public enum State {
STARTING,
STARTED,
