This is an automated email from the ASF dual-hosted git repository.
sk0x50 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 76ba73a524 IGNITE-18586 Added descriptions for REST components. Fixes
#1549
76ba73a524 is described below
commit 76ba73a524f687e9e035fec46279d939d29297c4
Author: IgGusev <[email protected]>
AuthorDate: Thu Feb 16 20:18:13 2023 +0200
IGNITE-18586 Added descriptions for REST components. Fixes #1549
Signed-off-by: Slava Koptilin <[email protected]>
---
.../ignite/internal/rest/api/InvalidParam.java | 4 +
.../apache/ignite/internal/rest/api/Problem.java | 12 +-
.../rest/api/cluster/ClusterManagementApi.java | 16 +-
.../internal/rest/api/cluster/ClusterNodeDto.java | 7 +-
.../internal/rest/api/cluster/ClusterStateDto.java | 6 +-
.../internal/rest/api/cluster/ClusterTagDto.java | 4 +-
.../internal/rest/api/cluster/InitCommand.java | 4 +
.../rest/api/cluster/NetworkAddressDto.java | 4 +-
.../internal/rest/api/cluster/NodeMetadataDto.java | 5 +-
.../internal/rest/api/cluster/TopologyApi.java | 12 +-
.../api/configuration/ClusterConfigurationApi.java | 34 ++--
.../api/configuration/NodeConfigurationApi.java | 30 ++--
.../internal/rest/api/metric/MetricSourceDto.java | 4 +-
.../internal/rest/api/metric/NodeMetricApi.java | 22 +--
.../internal/rest/api/node/NodeManagementApi.java | 10 +-
.../ignite/internal/rest/api/node/NodeState.java | 4 +
.../ignite/internal/rest/api/node/State.java | 3 +
modules/rest/openapi/openapi.yaml | 186 ++++++++++++---------
18 files changed, 220 insertions(+), 147 deletions(-)
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/InvalidParam.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/InvalidParam.java
index 671bfa0116..1d9442762d 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/InvalidParam.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/InvalidParam.java
@@ -20,13 +20,17 @@ package org.apache.ignite.internal.rest.api;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonGetter;
import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
import java.util.Objects;
/**
* Parameter validation result.
*/
+@Schema(description = "Information about invalid request parameter.")
public class InvalidParam {
+ @Schema(description = "Parameter name.")
private final String name;
+ @Schema(description = "The issue with the parameter.")
private final String reason;
@JsonCreator
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/Problem.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/Problem.java
index 2a5e630884..bba7dd9ce0 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/Problem.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/Problem.java
@@ -20,6 +20,7 @@ package org.apache.ignite.internal.rest.api;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonGetter;
import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
import java.util.Collection;
import java.util.Objects;
import java.util.UUID;
@@ -30,29 +31,38 @@ import org.jetbrains.annotations.Nullable;
/**
* Implements application/problem+json schema defined in <a
href="https://www.rfc-editor.org/rfc/rfc7807.html";>RFC-7807</a>.
*/
+@Schema(description = "Extended description of the problem with the request.")
public class Problem {
/** Short, human-readable summary of the problem type. */
+ @Schema(description = "Short summary of the issue.")
private final String title;
/** HTTP status code. */
+ @Schema(description = "Returned HTTP status code.")
private final int status;
/** Ignite 3 error code. */
+ @Schema(description = "Ignite 3 error code.")
private final String code;
/** URI to the error documentation (optional). */
+ @Schema(description = "URI to documentation regarding the issue.")
private final String type;
/** Human-readable explanation of the problem (optional). */
+ @Schema(description = "Extended explanation of the issue.")
private final String detail;
/** Ignite 3 node name (optional). */
+ @Schema(description = "Name of the node the issue happened on.")
private final String node;
/** Unique identifier that will help to trace the error in the log
(optional). */
+ @Schema(description = "Unique issue identifier. Thid identifier can be
used to find logs related to the issue")
private final UUID traceId;
- /** List of parameter that did not pass the validation (optional). */
+ /** List of parameters that did not pass the validation (optional). */
+ @Schema(description = "Parameters that did not pass validation.")
private final Collection<InvalidParam> invalidParams;
/** Constructor. */
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 ac1efddd1b..6429b4c6e5 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,12 +42,12 @@ public interface ClusterManagementApi {
* Returns cluster state.
*/
@Get("state")
- @Operation(operationId = "clusterState")
- @ApiResponse(responseCode = "200", description = "Return cluster state",
+ @Operation(operationId = "clusterState", description = "Returns current
cluster status.")
+ @ApiResponse(responseCode = "200", description = "Cluster status
returned.",
content = @Content(mediaType = MediaType.APPLICATION_JSON, schema
= @Schema(implementation = ClusterStateDto.class)))
- @ApiResponse(responseCode = "404", description = "Cluster state not found,
it means that the cluster is not initialized",
+ @ApiResponse(responseCode = "404", description = "Cluster state not found.
Most likely, the cluster is not initialized.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces({
MediaType.APPLICATION_JSON,
@@ -61,11 +61,11 @@ public interface ClusterManagementApi {
* @return Completable future that will be completed when cluster is
initialized.
*/
@Post("init")
- @Operation(operationId = "init")
- @ApiResponse(responseCode = "200", description = "Cluster initialized")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "init", description = "Initializes 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)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Consumes(MediaType.APPLICATION_JSON)
CompletableFuture<Void> init(@Body InitCommand initCommand);
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterNodeDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterNodeDto.java
index 5dc210af24..c2147d7147 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterNodeDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterNodeDto.java
@@ -26,17 +26,22 @@ import org.apache.ignite.network.ClusterNode;
/**
* REST representation of {@link ClusterNode}.
*/
-@Schema(name = "ClusterNode")
+@Schema(name = "ClusterNode", description = "Information about the cluster
node.")
+
public class ClusterNodeDto {
/** Local id assigned to this node instance. Changes between restarts. */
+ @Schema(description = "Node ID.")
private final String id;
/** Unique name of member in the cluster. Consistent between restarts. */
+ @Schema(description = "Unique cluster name.")
private final String name;
/** Network address of this node. */
+ @Schema(description = "Cluster network address information.")
private final NetworkAddressDto address;
+ @Schema(description = "Node metadata information.")
private final NodeMetadataDto metadata;
/**
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterStateDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterStateDto.java
index 082ace2fda..78fac0ebd5 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterStateDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterStateDto.java
@@ -26,14 +26,18 @@ import java.util.Objects;
/**
* REST representation of internal ClusterState.
*/
-@Schema(name = "ClusterState")
+@Schema(name = "ClusterState", description = "Information about current
cluster state.")
public class ClusterStateDto {
+ @Schema(description = "List of cluster management group nodes. These nodes
are responsible for maintaining RAFT cluster topology.")
private final Collection<String> cmgNodes;
+ @Schema(description = "List of metastorage nodes. These nodes are
responsible for storing RAFT cluster metadata.")
private final Collection<String> msNodes;
+ @Schema(description = "Version of Apache Ignite that the cluster was
created on.")
private final String igniteVersion;
+ @Schema(description = "Unique tag that identifies the cluster.")
private final ClusterTagDto clusterTag;
/**
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterTagDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterTagDto.java
index 5662e1d3f2..288ddb5cc2 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterTagDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/ClusterTagDto.java
@@ -26,12 +26,14 @@ import java.util.UUID;
/**
* REST representation of internal ClusterTag.
*/
-@Schema(name = "ClusterTag")
+@Schema(name = "ClusterTag", description = "Unique tag that identifies the
cluster.")
public class ClusterTagDto {
/** Auto-generated part. */
+ @Schema(description = "Unique cluster UUID. Generated automatically.")
private final UUID clusterId;
/** Human-readable part. */
+ @Schema(description = "Unique cluster name.")
private final String clusterName;
@JsonCreator
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/InitCommand.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/InitCommand.java
index d97869095b..ea3eeeb29c 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/InitCommand.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/InitCommand.java
@@ -21,6 +21,7 @@ import static
org.apache.ignite.internal.util.CollectionUtils.nullOrEmpty;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
import java.util.Collection;
import java.util.List;
import java.util.Objects;
@@ -31,10 +32,13 @@ import org.jetbrains.annotations.Nullable;
* REST command for initializing a cluster.
*/
public class InitCommand {
+ @Schema(description = "A list of RAFT metastorage nodes.")
private final Collection<String> metaStorageNodes;
+ @Schema(description = "A list of RAFT cluster management nodes.")
private final Collection<String> cmgNodes;
+ @Schema(description = "The name of the cluster.")
private final String clusterName;
/**
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NetworkAddressDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NetworkAddressDto.java
index 14de2baf5d..5735f78345 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NetworkAddressDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NetworkAddressDto.java
@@ -26,12 +26,14 @@ import org.apache.ignite.network.NetworkAddress;
/**
* REST representation of {@link NetworkAddress}.
*/
-@Schema(name = "NetworkAddress")
+@Schema(name = "NetworkAddress", description = "Node network address
information.")
public class NetworkAddressDto {
/** Host. */
+ @Schema(description = "Name of the host node is on.")
private final String host;
/** Port. */
+ @Schema(description = "Port the node runs on.")
private final int port;
/**
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NodeMetadataDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NodeMetadataDto.java
index c777febb3b..b914009305 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NodeMetadataDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/cluster/NodeMetadataDto.java
@@ -26,10 +26,13 @@ import org.apache.ignite.network.NodeMetadata;
/**
* REST representation of {@link NodeMetadata}.
*/
-@Schema(name = "NodeMetadata")
+@Schema(name = "NodeMetadata", description = "Node metadata information.")
public class NodeMetadataDto {
+ @Schema(description = "The host exposed to REST API.")
private final String restHost;
+ @Schema(description = "The HTTP port exposed to REST API.")
private final int httpPort;
+ @Schema(description = "The HTTPS port exposed to REST API.")
private final int httpsPort;
/**
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 9a6925d5ec..18a93fa48d 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,9 +40,9 @@ public interface TopologyApi {
* Cluster physical topology.
*/
@Get("physical")
- @Operation(operationId = "physical")
- @ApiResponse(responseCode = "200", description = "Physical topology
returned")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "physical", description = "Gets information about
physical cluster topology.")
+ @ApiResponse(responseCode = "200", description = "Physical topology
returned.")
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces(MediaType.APPLICATION_JSON)
Collection<ClusterNodeDto> physicalTopology();
@@ -51,9 +51,9 @@ public interface TopologyApi {
* Cluster logical topology.
*/
@Get("logical")
- @Operation(operationId = "logical")
- @ApiResponse(responseCode = "200", description = "Logical topology
returned")
- @ApiResponse(responseCode = "404", description = "Logical topology not
found, it means that the cluster is not initialized",
+ @Operation(operationId = "logical", description = "Gets information about
logical cluster topology.")
+ @ApiResponse(responseCode = "200", description = "Logical topology
returned.")
+ @ApiResponse(responseCode = "404", description = "Logical topology not
found. Most likely, the cluster is not initialized.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@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/configuration/ClusterConfigurationApi.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/configuration/ClusterConfigurationApi.java
index a58e6795fc..6f5e760acc 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
@@ -25,6 +25,7 @@ import io.micronaut.http.annotation.Patch;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Produces;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -44,16 +45,16 @@ public interface ClusterConfigurationApi {
*
* @return the whole cluster configuration in HOCON format.
*/
- @Operation(operationId = "getClusterConfiguration")
+ @Operation(operationId = "getClusterConfiguration", description = "Gets
the current configuration of the cluster.")
@ApiResponse(
responseCode = "200",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")),
description = "Get cluster configuration")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "404", description = "Configuration not found,
it means that the cluster is not initialized",
+ @ApiResponse(responseCode = "404", description = "Configuration not found.
Most likely, the cluster is not initialized.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces({
MediaType.TEXT_PLAIN,
@@ -67,13 +68,14 @@ public interface ClusterConfigurationApi {
*
* @param updatedConfiguration the cluster configuration to update.
*/
- @Operation(operationId = "updateClusterConfiguration")
- @ApiResponse(responseCode = "200", description = "Configuration updated")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "updateClusterConfiguration", 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)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "404", description = "Configuration not found,
it means that the cluster is not initialized",
+ @ApiResponse(responseCode = "404", description = "Configuration not found.
Most likely, the cluster is not initialized.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.PROBLEM_JSON)
@@ -86,20 +88,22 @@ public interface ClusterConfigurationApi {
* @param path to represent a cluster configuration.
* @return system configuration in HOCON format represented by given path.
*/
- @Operation(operationId = "getClusterConfigurationByPath")
+ @Operation(operationId = "getClusterConfigurationByPath",
+ description = "Gets the configuration on the specific path.
Configuration is in HOCON format")
@ApiResponse(responseCode = "200",
content = @Content(mediaType = MediaType.TEXT_PLAIN, schema =
@Schema(type = "string")),
- description = "Configuration represented by path")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ description = "Configuration of the cluster on the specified
path.")
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "404", description = "Configuration not found,
it means that the cluster is not initialized",
+ @ApiResponse(responseCode = "404", description = "Configuration not found.
Most likely, the cluster is not initialized.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces({
MediaType.TEXT_PLAIN,
MediaType.PROBLEM_JSON
})
@Get("/{path}")
- String getConfigurationByPath(@PathVariable("path") String path);
+ String getConfigurationByPath(@PathVariable("path") @Parameter(required =
true,
+ description = "Configuration tree address. For example:
`element.subelement`.") String path);
}
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 6f3ed5c60e..0b4d4b9f28 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
@@ -25,6 +25,7 @@ import io.micronaut.http.annotation.Patch;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.annotation.Produces;
import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
@@ -45,14 +46,14 @@ public interface NodeConfigurationApi {
*
* @return the whole node configuration in HOCON format.
*/
- @Operation(operationId = "getNodeConfiguration")
+ @Operation(operationId = "getNodeConfiguration", description = "Gets node
configuration in HOCON format.")
@ApiResponse(responseCode = "200",
content = @Content(mediaType = MediaType.TEXT_PLAIN,
schema = @Schema(type = "string")),
- description = "Whole node configuration")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ description = "Whole node configuration.")
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces({
MediaType.TEXT_PLAIN,
@@ -67,32 +68,35 @@ public interface NodeConfigurationApi {
* @param path to represent a node configuration.
* @return system configuration in HOCON format represented by given path.
*/
- @Operation(operationId = "getNodeConfigurationByPath")
+ @Operation(operationId = "getNodeConfigurationByPath",
+ 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 = "Configuration represented by path")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ description = "Returned node configuration.")
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces({
MediaType.TEXT_PLAIN,
MediaType.PROBLEM_JSON
})
@Get("/{path}")
- String getConfigurationByPath(@PathVariable("path") String path);
+ String getConfigurationByPath(@PathVariable("path") @Parameter(required =
true,
+ description = "Configuration tree address. For example:
`element.subelement`.") String path);
/**
* Updates node configuration in HOCON format. This is represented as a
plain text.
*
* @param updatedConfiguration the node configuration to update. This is
represented as a plain text.
*/
- @Operation(operationId = "updateNodeConfiguration")
- @ApiResponse(responseCode = "200", description = "Configuration updated")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "updateNodeConfiguration", 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)))
- @ApiResponse(responseCode = "400", description = "Incorrect configuration",
+ @ApiResponse(responseCode = "400", description = "Incorrect
configuration.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.PROBLEM_JSON)
diff --git
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/MetricSourceDto.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/MetricSourceDto.java
index 1cda8844b4..0198cd7460 100644
---
a/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/MetricSourceDto.java
+++
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/metric/MetricSourceDto.java
@@ -25,12 +25,14 @@ import io.swagger.v3.oas.annotations.media.Schema;
/**
* REST representation of MetricSource.
*/
-@Schema(name = "MetricSource")
+@Schema(name = "MetricSource", description = "Metric sources provided by
modules.")
public class MetricSourceDto {
/** Name of the metric source. */
+ @Schema(description = "Metric source name.")
private final String name;
/** Enabled. */
+ @Schema(description = "If True, the metric is tracked. Otherwise, the
metric is not tracked.")
private final boolean enabled;
/**
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 900affadaa..34bd902b57 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
@@ -38,11 +38,11 @@ import org.apache.ignite.internal.rest.constants.MediaType;
public interface NodeMetricApi {
/** Enable metric source. */
- @Operation(operationId = "enableNodeMetric")
- @ApiResponse(responseCode = "200", description = "Metric source enabled")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "enableNodeMetric", description = "Enables a
specific 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)))
- @ApiResponse(responseCode = "404", description = "Metric source not found",
+ @ApiResponse(responseCode = "404", description = "Metric source not
found.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.PROBLEM_JSON)
@@ -50,11 +50,11 @@ public interface NodeMetricApi {
void enable(@Body String srcName);
/** Disable metric source. */
- @Operation(operationId = "disableNodeMetric")
- @ApiResponse(responseCode = "200", description = "Metric source disabled")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "disableNodeMetric", description = "Disables a
specific 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)))
- @ApiResponse(responseCode = "404", description = "Metric source not found",
+ @ApiResponse(responseCode = "404", description = "Metric source not
found.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Consumes(MediaType.TEXT_PLAIN)
@Produces(MediaType.PROBLEM_JSON)
@@ -62,9 +62,9 @@ public interface NodeMetricApi {
void disable(@Body String srcName);
/** List metric sources. */
- @Operation(operationId = "listNodeMetrics")
- @ApiResponse(responseCode = "200", description = "Metric sources returned")
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @Operation(operationId = "listNodeMetrics", description = "Provides a list
of all available metric sources.")
+ @ApiResponse(responseCode = "200", description = "Returned a list of
metric sources.")
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON, schema =
@Schema(implementation = Problem.class)))
@Produces(MediaType.APPLICATION_JSON)
@Get()
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 de99719880..8961d71780 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,11 +37,11 @@ import org.apache.ignite.internal.rest.constants.MediaType;
public interface NodeManagementApi {
@Get("state")
- @Operation(operationId = "nodeState")
+ @Operation(operationId = "nodeState", description = "Gets current network
status.")
@ApiResponses({
- @ApiResponse(responseCode = "200", description = "Return node
state",
+ @ApiResponse(responseCode = "200", description = "Current node
status.",
content = @Content(mediaType = MediaType.APPLICATION_JSON,
schema = @Schema(implementation = NodeState.class))),
- @ApiResponse(responseCode = "500", description = "Internal error",
+ @ApiResponse(responseCode = "500", description = "Internal error.",
content = @Content(mediaType = MediaType.PROBLEM_JSON,
schema = @Schema(implementation = Problem.class)))
})
@Produces({
@@ -51,8 +51,8 @@ public interface NodeManagementApi {
NodeState state();
@Get("version")
- @Operation(operationId = "nodeVersion")
- @ApiResponse(responseCode = "200", description = "Return node version",
+ @Operation(operationId = "nodeVersion", 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",
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/node/NodeState.java
b/modules/rest-api/src/main/java/org/apache/ignite/internal/rest/api/node/NodeState.java
index c959fc9417..32a1af47a0 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
@@ -20,14 +20,18 @@ package org.apache.ignite.internal.rest.api.node;
import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonGetter;
import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
/**
* Node state that is returned by REST.
*/
+@Schema(description = "Node state.")
public class NodeState {
+ @Schema(description = "Unique node name.")
private String name;
+ @Schema(description = "Node status.")
private State state;
@JsonCreator
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 f32e2b1431..b0cc307d56 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
@@ -17,7 +17,10 @@
package org.apache.ignite.internal.rest.api.node;
+import io.swagger.v3.oas.annotations.media.Schema;
+
/** Node state. */
+@Schema(description = "Possible node statuses.")
public enum State {
STARTING,
STARTED,
diff --git a/modules/rest/openapi/openapi.yaml
b/modules/rest/openapi/openapi.yaml
index fcb5edfec0..cdc18481e7 100644
--- a/modules/rest/openapi/openapi.yaml
+++ b/modules/rest/openapi/openapi.yaml
@@ -12,6 +12,7 @@ paths:
post:
tags:
- clusterManagement
+ description: Initializes a new cluster.
operationId: init
parameters: []
requestBody:
@@ -22,19 +23,19 @@ paths:
required: true
responses:
"200":
- description: Cluster initialized
+ description: Cluster initialized.
content:
application/json:
schema:
$ref: '#/components/schemas/Void'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
@@ -43,24 +44,24 @@ paths:
get:
tags:
- clusterManagement
+ description: Returns current cluster status.
operationId: clusterState
parameters: []
responses:
"200":
- description: Return cluster state
+ description: Cluster status returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterState'
"404":
- description: "Cluster state not found, it means that the cluster is
not\
- \ initialized"
+ description: "Cluster state not found. Most likely, the cluster is
not initialized."
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
@@ -69,11 +70,12 @@ paths:
get:
tags:
- topology
+ description: Gets information about logical cluster topology.
operationId: logical
parameters: []
responses:
"200":
- description: Logical topology returned
+ description: Logical topology returned.
content:
application/json:
schema:
@@ -81,8 +83,8 @@ paths:
items:
$ref: '#/components/schemas/ClusterNode'
"404":
- description: "Logical topology not found, it means that the cluster
is not\
- \ initialized"
+ description: "Logical topology not found. Most likely, the cluster
is not\
+ \ initialized."
content:
application/problem+json:
schema:
@@ -97,11 +99,12 @@ paths:
get:
tags:
- topology
+ description: Gets information about physical cluster topology.
operationId: physical
parameters: []
responses:
"200":
- description: Physical topology returned
+ description: Physical topology returned.
content:
application/json:
schema:
@@ -109,7 +112,7 @@ paths:
items:
$ref: '#/components/schemas/ClusterNode'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
@@ -118,6 +121,7 @@ paths:
get:
tags:
- clusterConfiguration
+ description: Gets the current configuration of the cluster.
operationId: getClusterConfiguration
parameters: []
responses:
@@ -128,20 +132,19 @@ paths:
schema:
type: string
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"404":
- description: "Configuration not found, it means that the cluster is
not\
- \ initialized"
+ description: "Configuration not found. Most likely, the cluster is
not initialized."
content:
application/problem+json:
schema:
@@ -149,6 +152,8 @@ paths:
patch:
tags:
- clusterConfiguration
+ description: Updates cluster configuration. New configuration should be
provided
+ in HOCON format.
operationId: updateClusterConfiguration
parameters: []
requestBody:
@@ -159,26 +164,25 @@ paths:
required: true
responses:
"200":
- description: Configuration updated
+ description: Configuration updated.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Void'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"404":
- description: "Configuration not found, it means that the cluster is
not\
- \ initialized"
+ description: "Configuration not found. Most likely, the cluster is
not initialized."
content:
application/problem+json:
schema:
@@ -187,35 +191,37 @@ paths:
get:
tags:
- clusterConfiguration
+ description: Gets the configuration on the specific path. Configuration
is in
+ HOCON format
operationId: getClusterConfigurationByPath
parameters:
- name: path
in: path
+ description: "Configuration tree address. For example:
`element.subelement`."
required: true
schema:
type: string
responses:
"200":
- description: Configuration represented by path
+ description: Configuration of the cluster on the specified path.
content:
text/plain:
schema:
type: string
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"404":
- description: "Configuration not found, it means that the cluster is
not\
- \ initialized"
+ description: "Configuration not found. Most likely, the cluster is
not initialized."
content:
application/problem+json:
schema:
@@ -224,23 +230,24 @@ paths:
get:
tags:
- nodeConfiguration
+ description: Gets node configuration in HOCON format.
operationId: getNodeConfiguration
parameters: []
responses:
"200":
- description: Whole node configuration
+ description: Whole node configuration.
content:
text/plain:
schema:
type: string
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
@@ -248,6 +255,8 @@ paths:
patch:
tags:
- nodeConfiguration
+ description: Updates node configuration. New configuration should be
provided
+ in HOCON format.
operationId: updateNodeConfiguration
parameters: []
requestBody:
@@ -258,19 +267,19 @@ paths:
required: true
responses:
"200":
- description: Configuration updated
+ description: Configuration successfully updated.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Void'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
@@ -279,28 +288,30 @@ paths:
get:
tags:
- nodeConfiguration
+ description: "Gets a configuration of a specific node, in HOCON format."
operationId: getNodeConfigurationByPath
parameters:
- name: path
in: path
+ description: "Configuration tree address. For example:
`element.subelement`."
required: true
schema:
type: string
responses:
"200":
- description: Configuration represented by path
+ description: Returned node configuration.
content:
text/plain:
schema:
type: string
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"400":
- description: Incorrect configuration
+ description: Incorrect configuration.
content:
application/problem+json:
schema:
@@ -309,11 +320,12 @@ paths:
get:
tags:
- nodeMetric
+ description: Provides a list of all available metric sources.
operationId: listNodeMetrics
parameters: []
responses:
"200":
- description: Metric sources returned
+ description: Returned a list of metric sources.
content:
application/json:
schema:
@@ -321,7 +333,7 @@ paths:
items:
$ref: '#/components/schemas/MetricSource'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
@@ -330,6 +342,7 @@ paths:
post:
tags:
- nodeMetric
+ description: Disables a specific metric source.
operationId: disableNodeMetric
parameters: []
requestBody:
@@ -340,15 +353,15 @@ paths:
required: true
responses:
"200":
- description: Metric source disabled
+ description: Metric source disabled.
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"404":
- description: Metric source not found
+ description: Metric source not found.
content:
application/problem+json:
schema:
@@ -357,6 +370,7 @@ paths:
post:
tags:
- nodeMetric
+ description: Enables a specific metric source.
operationId: enableNodeMetric
parameters: []
requestBody:
@@ -367,15 +381,15 @@ paths:
required: true
responses:
"200":
- description: Metric source enabled
+ description: Metric source enabled.
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
"404":
- description: Metric source not found
+ description: Metric source not found.
content:
application/problem+json:
schema:
@@ -384,17 +398,18 @@ paths:
get:
tags:
- nodeManagement
+ description: Gets current network status.
operationId: nodeState
parameters: []
responses:
"200":
- description: Return node state
+ description: Current node status.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeState'
"500":
- description: Internal error
+ description: Internal error.
content:
application/problem+json:
schema:
@@ -403,11 +418,12 @@ paths:
get:
tags:
- nodeManagement
+ description: Gets the version of Apache Ignite the node uses.
operationId: nodeVersion
parameters: []
responses:
"200":
- description: Return node version
+ description: Node version.
content:
text/plain:
schema:
@@ -421,153 +437,159 @@ paths:
components:
schemas:
ClusterNode:
- required:
- - address
- - id
- - metadata
- - name
type: object
properties:
id:
type: string
+ description: Node ID.
name:
type: string
+ description: Unique cluster name.
address:
$ref: '#/components/schemas/NetworkAddress'
metadata:
$ref: '#/components/schemas/NodeMetadata'
+ description: Information about the cluster node.
ClusterState:
- required:
- - clusterTag
- - cmgNodes
- - igniteVersion
- - msNodes
type: object
properties:
cmgNodes:
type: array
+ description: List of cluster management group nodes. These nodes are
responsible
+ for maintaining RAFT cluster topology.
items:
type: string
msNodes:
type: array
+ description: List of metastorage nodes. These nodes are responsible
for
+ storing RAFT cluster metadata.
items:
type: string
igniteVersion:
type: string
+ description: Version of Apache Ignite that the cluster was created
on.
clusterTag:
$ref: '#/components/schemas/ClusterTag'
+ description: Information about current cluster state.
ClusterTag:
- required:
- - clusterId
- - clusterName
type: object
properties:
clusterId:
type: string
+ description: Unique cluster UUID. Generated automatically.
format: uuid
clusterName:
type: string
+ description: Unique cluster name.
+ description: Unique tag that identifies the cluster.
InitCommand:
- required:
- - clusterName
- - metaStorageNodes
type: object
properties:
metaStorageNodes:
type: array
+ description: A list of RAFT metastorage nodes.
items:
type: string
cmgNodes:
type: array
+ description: A list of RAFT cluster management nodes.
items:
type: string
clusterName:
type: string
+ description: The name of the cluster.
InvalidParam:
- required:
- - name
- - reason
type: object
properties:
name:
type: string
+ description: Parameter name.
reason:
type: string
+ description: The issue with the parameter.
+ description: Information about invalid request parameter.
MetricSource:
- required:
- - enabled
- - name
type: object
properties:
name:
type: string
+ description: Metric source name.
enabled:
type: boolean
+ description: "If True, the metric is tracked. Otherwise, the metric
is not\
+ \ tracked."
+ description: Metric sources provided by modules.
NetworkAddress:
- required:
- - host
- - port
type: object
properties:
host:
type: string
+ description: Name of the host node is on.
port:
type: integer
+ description: Port the node runs on.
format: int32
+ description: Node network address information.
NodeMetadata:
- required:
- - httpPort
- - httpsPort
- - restHost
type: object
properties:
restHost:
type: string
+ description: The host exposed to REST API.
httpPort:
type: integer
+ description: The HTTP port exposed to REST API.
format: int32
httpsPort:
type: integer
+ description: The HTTPS port exposed to REST API.
format: int32
+ description: Node metadata information.
NodeState:
- required:
- - name
- - state
type: object
properties:
name:
type: string
+ description: Unique node name.
state:
$ref: '#/components/schemas/State'
+ description: Node state.
Problem:
- required:
- - code
- - status
- - title
type: object
properties:
title:
type: string
+ description: Short summary of the issue.
status:
type: integer
+ description: Returned HTTP status code.
format: int32
code:
type: string
+ description: Ignite 3 error code.
type:
type: string
+ description: URI to documentation regarding the issue.
detail:
type: string
+ description: Extended explanation of the issue.
node:
type: string
+ description: Name of the node the issue happened on.
traceId:
type: string
+ description: Unique issue identifier. Thid identifier can be used to
find
+ logs related to the issue
format: uuid
invalidParams:
type: array
+ description: Parameters that did not pass validation.
items:
$ref: '#/components/schemas/InvalidParam'
+ description: Extended description of the problem with the request.
State:
type: string
+ description: Possible node statuses.
enum:
- STARTING
- STARTED
