Add example values for request/response examples in swagger (#1441)
* Swagger support initial concept Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add descriptions for Target tags Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add target filter queries descriptions Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add target api descriptions Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add software modules API descriptions Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add descriptions for DS, DSTags and SMTypes Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add DistributionSetType API descriptions Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add Rollout API descriptions Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Bring back test scope to mariaDb Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add tags and descriptions to System config API Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Move away OpenAPI config from Start.java Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * provide license header and project version for openapi Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Fix error responses with example error body Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add DDI API to swagger and make proper API grouping Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Revert changes from not merging before commit Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Remove more changes Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * fix circle ci build Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add missing descriptions for downloadArtifact methods in DDI Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Make configuration for openApi conditional for flexibility in transitive dependencies Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Make beans conditional not config Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Remove oAuth and switch to more general description Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * remove comment Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> * Add example schema values for request responses examples Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io> --------- Signed-off-by: Stanislav Trailov <Stanislav.Trailov@bosch.io>
This commit is contained in:
Stanislav Trailov
committed by
GitHub
GitHub
parent
5eb84cba4e
commit
60f14691fc
@@ -15,6 +15,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* <p>
|
||||
@@ -39,6 +40,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class DdiActionFeedback {
|
||||
|
||||
@Schema(example = "2023-08-03T12:31:41.890992967Z")
|
||||
private final String time;
|
||||
|
||||
@NotNull
|
||||
|
||||
@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.ddi.json.model;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.eclipse.hawkbit.ddi.rest.api.DdiRootControllerRestApi;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
@@ -32,6 +33,7 @@ import com.fasterxml.jackson.annotation.JsonPropertyOrder;
|
||||
public class DdiActionHistory {
|
||||
|
||||
@JsonProperty("status")
|
||||
@Schema(example = "RUNNING")
|
||||
private final String actionStatus;
|
||||
|
||||
@JsonProperty("messages")
|
||||
|
||||
@@ -12,14 +12,17 @@ package org.eclipse.hawkbit.ddi.json.model;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class DdiActivateAutoConfirmation {
|
||||
|
||||
@JsonProperty(required = false)
|
||||
@Schema(example = "exampleUser")
|
||||
private final String initiator;
|
||||
|
||||
@JsonProperty(required = false)
|
||||
@Schema(example = "exampleRemark")
|
||||
private final String remark;
|
||||
|
||||
/**
|
||||
|
||||
@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.ddi.json.model;
|
||||
|
||||
import javax.validation.constraints.NotNull;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.springframework.hateoas.RepresentationModel;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
@@ -25,12 +26,14 @@ public class DdiArtifact extends RepresentationModel<DdiArtifact> {
|
||||
|
||||
@NotNull
|
||||
@JsonProperty
|
||||
@Schema(example = "binary.tgz")
|
||||
private String filename;
|
||||
|
||||
@JsonProperty
|
||||
private DdiArtifactHash hashes;
|
||||
|
||||
@JsonProperty
|
||||
@Schema(example = "3")
|
||||
private Long size;
|
||||
|
||||
public DdiArtifactHash getHashes() {
|
||||
|
||||
@@ -13,6 +13,7 @@ import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude.Include;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Hashes for given Artifact.
|
||||
@@ -21,13 +22,16 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
public class DdiArtifactHash {
|
||||
|
||||
@JsonProperty
|
||||
@Schema(example = "2d86c2a659e364e9abba49ea6ffcd53dd5559f05")
|
||||
private String sha1;
|
||||
|
||||
@JsonProperty
|
||||
@Schema(example = "0d1b08c34858921bc7c662b228acb7ba")
|
||||
private String md5;
|
||||
|
||||
@JsonProperty
|
||||
@JsonInclude(Include.NON_NULL)
|
||||
@Schema(example = "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615")
|
||||
private String sha256;
|
||||
|
||||
/**
|
||||
|
||||
@@ -14,6 +14,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.springframework.hateoas.RepresentationModel;
|
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL)
|
||||
@@ -22,10 +23,14 @@ import org.springframework.hateoas.RepresentationModel;
|
||||
public class DdiAutoConfirmationState extends RepresentationModel<DdiAutoConfirmationState> {
|
||||
|
||||
@NotNull
|
||||
@Schema(example = "true")
|
||||
private boolean active;
|
||||
@Schema(example = "exampleUserId")
|
||||
private String initiator;
|
||||
@Schema(example = "exampleRemark")
|
||||
private String remark;
|
||||
|
||||
@Schema(example = "1691065895439")
|
||||
private Long activatedAt;
|
||||
|
||||
/**
|
||||
|
||||
@@ -14,6 +14,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Cancel action to be provided to the target.
|
||||
@@ -21,6 +22,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class DdiCancel {
|
||||
|
||||
@Schema(example = "11")
|
||||
private final String id;
|
||||
|
||||
@NotNull
|
||||
|
||||
@@ -14,6 +14,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* The action that has to be stopped by the target.
|
||||
@@ -22,6 +23,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
public class DdiCancelActionToStop {
|
||||
|
||||
@NotNull
|
||||
@Schema(example = "11")
|
||||
private final String stopId;
|
||||
|
||||
/**
|
||||
|
||||
@@ -17,6 +17,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Deployment chunks.
|
||||
@@ -26,14 +27,17 @@ public class DdiChunk {
|
||||
|
||||
@JsonProperty("part")
|
||||
@NotNull
|
||||
@Schema(example = "bApp")
|
||||
private String part;
|
||||
|
||||
@JsonProperty("version")
|
||||
@NotNull
|
||||
@Schema(example = "1.2.0")
|
||||
private String version;
|
||||
|
||||
@JsonProperty("name")
|
||||
@NotNull
|
||||
@Schema(example = "oneApp")
|
||||
private String name;
|
||||
|
||||
@JsonProperty("encrypted")
|
||||
|
||||
@@ -7,8 +7,9 @@
|
||||
*
|
||||
* SPDX-License-Identifier: EPL-2.0
|
||||
*/
|
||||
package org.eclipse.hawkbit.ddi.json.model;
|
||||
package org.eclipse.hawkbit.ddi.json.model;
|
||||
|
||||
import java.util.HashMap;
|
||||
import java.util.Map;
|
||||
|
||||
import javax.validation.constraints.NotEmpty;
|
||||
@@ -16,6 +17,7 @@ import javax.validation.constraints.NotEmpty;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Feedback channel for ConfigData action.
|
||||
@@ -26,6 +28,7 @@ public class DdiConfigData {
|
||||
@NotEmpty
|
||||
private final Map<String, String> data;
|
||||
|
||||
@Schema(example = "merge")
|
||||
private final DdiUpdateMode mode;
|
||||
|
||||
/**
|
||||
|
||||
@@ -13,6 +13,7 @@ import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.springframework.hateoas.RepresentationModel;
|
||||
|
||||
import javax.validation.constraints.NotNull;
|
||||
@@ -27,6 +28,7 @@ public class DdiConfirmationBaseAction extends RepresentationModel<DdiConfirmati
|
||||
|
||||
@JsonProperty("id")
|
||||
@NotNull
|
||||
@Schema(example = "6")
|
||||
private String id;
|
||||
|
||||
@JsonProperty("confirmation")
|
||||
|
||||
@@ -13,6 +13,7 @@ import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonValue;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
import javax.validation.Valid;
|
||||
import javax.validation.constraints.NotNull;
|
||||
@@ -32,6 +33,7 @@ public class DdiConfirmationFeedback {
|
||||
@Valid
|
||||
private final Confirmation confirmation;
|
||||
|
||||
@Schema(example = "200")
|
||||
private final Integer code;
|
||||
|
||||
private final List<String> details;
|
||||
|
||||
@@ -11,6 +11,7 @@ package org.eclipse.hawkbit.ddi.json.model;
|
||||
|
||||
import javax.validation.constraints.NotNull;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import org.springframework.hateoas.RepresentationModel;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
@@ -27,6 +28,7 @@ public class DdiDeploymentBase extends RepresentationModel<DdiDeploymentBase> {
|
||||
|
||||
@JsonProperty("id")
|
||||
@NotNull
|
||||
@Schema(example = "8")
|
||||
private String id;
|
||||
|
||||
@JsonProperty("deployment")
|
||||
|
||||
@@ -14,6 +14,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Additional metadata to be provided for the target/device.
|
||||
@@ -23,10 +24,12 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
public class DdiMetadata {
|
||||
@JsonProperty
|
||||
@NotNull
|
||||
@Schema(example = "aMetadataKey")
|
||||
private final String key;
|
||||
|
||||
@JsonProperty
|
||||
@NotNull
|
||||
@Schema(example = "Metadata value as defined in software module")
|
||||
private final String value;
|
||||
|
||||
@JsonCreator
|
||||
|
||||
@@ -13,6 +13,10 @@ import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude.Include;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
|
||||
import com.fasterxml.jackson.annotation.JsonValue;
|
||||
import io.swagger.v3.oas.annotations.media.ExampleObject;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Polling interval for the SP target.
|
||||
@@ -22,6 +26,7 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
public class DdiPolling {
|
||||
|
||||
@JsonProperty
|
||||
@Schema(example = "12:00:00")
|
||||
private String sleep;
|
||||
|
||||
/**
|
||||
|
||||
@@ -14,6 +14,7 @@ import javax.validation.constraints.NotNull;
|
||||
import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Action fulfillment progress by means of gives the achieved amount of maximal
|
||||
@@ -23,8 +24,10 @@ import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
public class DdiProgress {
|
||||
|
||||
@NotNull
|
||||
@Schema(example = "2")
|
||||
private final Integer cnt;
|
||||
|
||||
@Schema(example = "5")
|
||||
private final Integer of;
|
||||
|
||||
/**
|
||||
|
||||
@@ -16,6 +16,7 @@ import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonValue;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Result information of the action progress which can by an intermediate or
|
||||
|
||||
@@ -19,6 +19,7 @@ import com.fasterxml.jackson.annotation.JsonCreator;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonValue;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
|
||||
/**
|
||||
* Details status information concerning the action processing.
|
||||
@@ -34,6 +35,7 @@ public class DdiStatus {
|
||||
@Valid
|
||||
private final DdiResult result;
|
||||
|
||||
@Schema(example = "200")
|
||||
private final Integer code;
|
||||
|
||||
private final List<String> details;
|
||||
|
||||
@@ -449,8 +449,9 @@ public interface DdiRootControllerRestApi {
|
||||
""")
|
||||
@ApiResponses(value = {
|
||||
@ApiResponse(responseCode = "200", description = """
|
||||
|
||||
""", content = @Content(schema = @Schema(oneOf = {}))), //TODO: 2 RESPONSES WHEN AUTO CONFIRMATION IS ACTIVE OR NOT
|
||||
The response body in case auto-confirmation is active is richer - it contains additional information
|
||||
such as initiator, remark and when the auto-confirmation had been activated.
|
||||
"""),
|
||||
@ApiResponse(responseCode = "400", description = "Bad Request - e.g. invalid parameters", content = @Content(mediaType = "application/json", schema = @Schema(implementation = ExceptionInfo.class))),
|
||||
@ApiResponse(responseCode = "401", description = "The request requires user authentication.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
|
||||
@ApiResponse(responseCode = "403", description = "Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.", content = @Content(mediaType = "application/json", schema = @Schema(hidden = true))),
|
||||
|
||||
Reference in New Issue
Block a user