Add example values for request/response examples in swagger (#1441)

* Swagger support initial concept Signed-off-by: Stanislav Trailov <[email protected]> * Add descriptions for Target tags Signed-off-by: Stanislav Trailov <[email protected]> * Add target filter queries descriptions Signed-off-by: Stanislav Trailov <[email protected]> * Add target api descriptions Signed-off-by: Stanislav Trailov <[email protected]> * Add software modules API descriptions Signed-off-by: Stanislav Trailov <[email protected]> * Add descriptions for DS, DSTags and SMTypes Signed-off-by: Stanislav Trailov <[email protected]> * Add DistributionSetType API descriptions Signed-off-by: Stanislav Trailov <[email protected]> * Add Rollout API descriptions Signed-off-by: Stanislav Trailov <[email protected]> * Bring back test scope to mariaDb Signed-off-by: Stanislav Trailov <[email protected]> * Add tags and descriptions to System config API Signed-off-by: Stanislav Trailov <[email protected]> * Move away OpenAPI config from Start.java Signed-off-by: Stanislav Trailov <[email protected]> * provide license header and project version for openapi Signed-off-by: Stanislav Trailov <[email protected]> * Fix error responses with example error body Signed-off-by: Stanislav Trailov <[email protected]> * Add DDI API to swagger and make proper API grouping Signed-off-by: Stanislav Trailov <[email protected]> * Revert changes from not merging before commit Signed-off-by: Stanislav Trailov <[email protected]> * Remove more changes Signed-off-by: Stanislav Trailov <[email protected]> * fix circle ci build Signed-off-by: Stanislav Trailov <[email protected]> * Add missing descriptions for downloadArtifact methods in DDI Signed-off-by: Stanislav Trailov <[email protected]> * Make configuration for openApi conditional for flexibility in transitive dependencies Signed-off-by: Stanislav Trailov <[email protected]> * Make beans conditional not config Signed-off-by: Stanislav Trailov <[email protected]> * Remove oAuth and switch to more general description Signed-off-by: Stanislav Trailov <[email protected]> * remove comment Signed-off-by: Stanislav Trailov <[email protected]> * Add example schema values for request responses examples Signed-off-by: Stanislav Trailov <[email protected]> --------- Signed-off-by: Stanislav Trailov <[email protected]>
eclipse-hawkbit · Sep 29, 2023 · 60f1469 · 60f1469
1 parent 5eb84cb
commit 60f1469
Show file tree

Hide file tree

Showing 68 changed files with 279 additions and 3 deletions.
diff --git a/...t/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActionFeedback.java b/...t/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActionFeedback.java
@@ -15,6 +15,7 @@
 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 @@
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class DdiActionFeedback {
 
+    @Schema(example = "2023-08-03T12:31:41.890992967Z")
     private final String time;
 
     @NotNull

diff --git a/...st/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActionHistory.java b/...st/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActionHistory.java
@@ -11,6 +11,7 @@
 
 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 @@
 public class DdiActionHistory {
 
     @JsonProperty("status")
+    @Schema(example = "RUNNING")
     private final String actionStatus;
 
     @JsonProperty("messages")

diff --git a/...ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActivateAutoConfirmation.java b/...ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiActivateAutoConfirmation.java
@@ -12,14 +12,17 @@
 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;
 
     /**

diff --git a/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiArtifact.java b/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiArtifact.java
@@ -11,6 +11,7 @@
 
 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() {

diff --git a/...est/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiArtifactHash.java b/...est/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiArtifactHash.java
@@ -13,6 +13,7 @@
 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 @@
 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;
 
     /**

diff --git a/...it-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiAutoConfirmationState.java b/...it-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiAutoConfirmationState.java
@@ -14,6 +14,7 @@
 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 @@
 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;
 
     /**

diff --git a/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiCancel.java b/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiCancel.java
@@ -14,13 +14,15 @@
 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.
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class DdiCancel {
 
+    @Schema(example = "11")
     private final String id;
 
     @NotNull

diff --git a/...wkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiCancelActionToStop.java b/...wkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiCancelActionToStop.java
@@ -14,6 +14,7 @@
 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 @@
 public class DdiCancelActionToStop {
 
     @NotNull
+    @Schema(example = "11")
     private final String stopId;
 
     /**

diff --git a/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiChunk.java b/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiChunk.java
@@ -17,6 +17,7 @@
 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")

diff --git a/...-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfigData.java b/...-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfigData.java
@@ -7,15 +7,17 @@
  *
  * 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;
 
 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;
 
     /**

diff --git a/...t-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfirmationBaseAction.java b/...t-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfirmationBaseAction.java
@@ -13,6 +13,7 @@
 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")

diff --git a/...bit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfirmationFeedback.java b/...bit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiConfirmationFeedback.java
@@ -13,6 +13,7 @@
 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;

diff --git a/...t/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiDeploymentBase.java b/...t/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiDeploymentBase.java
@@ -11,6 +11,7 @@
 
 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")

diff --git a/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiMetadata.java b/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiMetadata.java
@@ -14,6 +14,7 @@
 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 @@
 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

diff --git a/...bit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiPolling.java b/...bit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiPolling.java
@@ -13,6 +13,10 @@
 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 @@
 public class DdiPolling {
 
     @JsonProperty
+    @Schema(example = "12:00:00")
     private String sleep;
 
     /**

diff --git a/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiProgress.java b/...it-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiProgress.java
@@ -14,6 +14,7 @@
 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 @@
 public class DdiProgress {
 
     @NotNull
+    @Schema(example = "2")
     private final Integer cnt;
 
+    @Schema(example = "5")
     private final Integer of;
 
     /**

diff --git a/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiResult.java b/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiResult.java
@@ -16,6 +16,7 @@
 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

diff --git a/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiStatus.java b/hawkbit-rest/hawkbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/json/model/DdiStatus.java
@@ -19,6 +19,7 @@
 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;

diff --git a/...kbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/rest/api/DdiRootControllerRestApi.java b/...kbit-ddi-api/src/main/java/org/eclipse/hawkbit/ddi/rest/api/DdiRootControllerRestApi.java
@@ -449,8 +449,9 @@ ResponseEntity<DdiDeploymentBase> getControllerInstalledAction(@PathVariable("te
         """)
     @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))),

diff --git a/...st/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java b/...st/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtBaseEntity.java
@@ -9,6 +9,7 @@
  */
 package org.eclipse.hawkbit.mgmt.json.model;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.springframework.hateoas.Link;
 import org.springframework.hateoas.RepresentationModel;
 
@@ -22,15 +23,19 @@
 public abstract class MgmtBaseEntity extends RepresentationModel<MgmtBaseEntity> {
 
     @JsonProperty
+    @Schema(example = "bumlux")
     private String createdBy;
 
     @JsonProperty
+    @Schema(example = "1691065905897")
     private Long createdAt;
 
     @JsonProperty
+    @Schema(example = "bumlux")
     private String lastModifiedBy;
 
     @JsonProperty
+    @Schema(example = "1691065906407")
     private Long lastModifiedAt;
 
     /**

diff --git a/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtId.java b/hawkbit-rest/hawkbit-mgmt-api/src/main/java/org/eclipse/hawkbit/mgmt/json/model/MgmtId.java
@@ -11,6 +11,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 /**
  * A generic abstract rest model which contains only a ID for use-case e.g.
@@ -20,6 +21,7 @@
  */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class MgmtId {
+    @Schema(example = "108")
     private Long id;
 
     /**