add missing OpenAPI descriptions

Author: goekay

src/main/java/de/rwth/idsg/steve/repository/dto/OcppTag.java

@@ -36,13 +36,22 @@ public final class OcppTag {
     @Builder
     @ToString
     public static final class Overview {
+        @Schema(description = "PK of the OCPP tag")
         private final Integer ocppTagPk;
+
+        @Schema(description = "The OCPP tag")
         private final String idTag;
 
+        @Schema(description = "PK of the parent OCPP tag of this OCPP tag")
         private final Integer parentOcppTagPk;
+
+        @Schema(description = "The parent OCPP tag of this OCPP tag")
         private final String parentIdTag;
 
+        @Schema(description = "Has the OCPP tag active transactions (i.e. ongoing charging sessions)?")
         private final boolean inTransaction;
+
+        @Schema(description = "Is the OCPP tag blocked?")
         private final boolean blocked;
 
         /**
@@ -52,10 +61,16 @@ public static final class Overview {
         @Schema(hidden = true)
         private final String expiryDateFormatted;
 
+        @Schema(description = "The date/time at which the OCPP tag will expire (if set)")
         private final DateTime expiryDate;
 
+        @Schema(description = "The maximum number of active transactions allowed for this OCPP tag")
         private final Integer maxActiveTransactionCount;
+
+        @Schema(description = "The number of currently active transactions for this OCPP tag")
         private final Long activeTransactionCount;
+
+        @Schema(description = "An additional note")
         private final String note;
     }
 }

src/main/java/de/rwth/idsg/steve/repository/dto/Transaction.java

@@ -32,18 +32,32 @@
  * @author Sevket Goekay <[email protected]>
  *
  */
+@Schema(description = """
+        For active transactions, all 'stop'-prefixed fields would be null.
+        The energy consumed during the transaction can be calculated by subtracting the 'startValue' from the 'stopValue'.
+        The unit of the 'startValue' and 'stopValue' is watt-hours (Wh).
+        """)
 @Getter
 @Builder
 @ToString
 public final class Transaction {
 
+    @Schema(description = "PK of the transaction")
     private final int id;
+
+    @Schema(description = "Connector ID of the charge box at which the transaction took place")
     private final int connectorId;
+
+    @Schema(description = "PK of the charge box at which the transaction took place")
     private final int chargeBoxPk;
+
+    @Schema(description = "PK of the OCPP tag used in the transaction")
     private final int ocppTagPk;
 
+    @Schema(description = "The identifier of the charge box at which the transaction took place")
     private final String chargeBoxId;
 
+    @Schema(description = "The Ocpp Tag used in the transaction")
     private final String ocppIdTag;
 
     /**
@@ -53,8 +67,10 @@ public final class Transaction {
     @Schema(hidden = true)
     private final String startTimestampFormatted;
 
+    @Schema(description = "The meter value reading at the start of the transaction")
     private final String startValue;
 
+    @Schema(description = "The timestamp at which the transaction started")
     private final DateTime startTimestamp;
 
     /**
@@ -66,14 +82,18 @@ public final class Transaction {
     private final String stopTimestampFormatted;
 
     @Nullable
+    @Schema(description = "The meter value reading at the end of the transaction")
     private final String stopValue;
 
     @Nullable
+    @Schema(description = "The reason for the transaction being stopped")
     private final String stopReason; // new in OCPP 1.6
 
     @Nullable
+    @Schema(description = "The timestamp at which the transaction ended")
     private final DateTime stopTimestamp;
 
     @Nullable
+    @Schema(description = "The actor who stopped the transaction")
     private final TransactionStopEventActor stopEventActor;
 }

src/main/java/de/rwth/idsg/steve/web/api/OcppTagsRestController.java

@@ -24,10 +24,12 @@
 import de.rwth.idsg.steve.web.api.ApiControllerAdvice.ApiErrorResponse;
 import de.rwth.idsg.steve.web.dto.OcppTagForm;
 import de.rwth.idsg.steve.web.dto.OcppTagQueryForm;
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatus;
@@ -50,6 +52,14 @@
  * @author Sevket Goekay <[email protected]>
  * @since 13.09.2022
  */
+@Tag(name = "ocpp-tag-controller",
+    description = """
+        Operations related to managing Ocpp Tags.
+        An Ocpp Tag is the identifier of the actor that interacts with the charge box.
+        It can be used for authorization, but also to start and stop charging sessions.
+        An RFID card is an example of an Ocpp Tag.
+        """
+)
 @Slf4j
 @RestController
 @RequestMapping(value = "/api/v1/ocppTags", produces = MediaType.APPLICATION_JSON_VALUE)
@@ -58,7 +68,10 @@ public class OcppTagsRestController {
 
     private final OcppTagService ocppTagService;
 
-
+    @Operation(description = """
+        Returns a list of Ocpp Tags based on the query parameters.
+        The query parameters can be used to filter the Ocpp Tags.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "OK"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),
@@ -75,6 +88,9 @@ public List<OcppTag.Overview> get(OcppTagQueryForm.ForApi params) {
         return response;
     }
 
+    @Operation(description = """
+        Returns a single Ocpp Tag based on the ocppTagPk.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "OK"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),
@@ -92,6 +108,10 @@ public OcppTag.Overview getOne(@PathVariable("ocppTagPk") Integer ocppTagPk) {
         return response;
     }
 
+    @Operation(description = """
+        Creates a new Ocpp Tag with the provided parameters.
+        The request body should contain the necessary information.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "201", description = "Created"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),
@@ -113,6 +133,9 @@ public OcppTag.Overview create(@RequestBody @Valid OcppTagForm params) {
         return response;
     }
 
+    @Operation(description = """
+        Updates an existing Ocpp Tag with the provided parameters.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "OK"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),
@@ -133,6 +156,10 @@ public OcppTag.Overview update(@PathVariable("ocppTagPk") Integer ocppTagPk, @Re
         return response;
     }
 
+    @Operation(description = """
+        Deletes an existing Ocpp Tag based on the ocppTagPk.
+        Returns the deleted Ocpp Tag.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "OK"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),

src/main/java/de/rwth/idsg/steve/web/api/TransactionsRestController.java

@@ -23,10 +23,12 @@
 import de.rwth.idsg.steve.web.api.ApiControllerAdvice.ApiErrorResponse;
 import de.rwth.idsg.steve.web.api.exception.BadRequestException;
 import de.rwth.idsg.steve.web.dto.TransactionQueryForm;
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.media.Content;
 import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.MediaType;
@@ -42,6 +44,12 @@
  * @author Sevket Goekay <[email protected]>
  * @since 13.09.2022
  */
+@Tag(name = "transaction-controller",
+    description = """
+        Operations related to querying transactions.
+        A transaction represents a charging session at a charge box (i.e. charging station. The notions 'charge box' and 'charging station' are being used interchangeably).
+        """
+)
 @Slf4j
 @RestController
 @RequestMapping(value = "/api/v1/transactions", produces = MediaType.APPLICATION_JSON_VALUE)
@@ -50,6 +58,10 @@ public class TransactionsRestController {
 
     private final TransactionRepository transactionRepository;
 
+    @Operation(description = """
+        Returns a list of transactions based on the query parameters.
+        The query parameters can be used to filter the transactions.
+        """)
     @ApiResponses(value = {
         @ApiResponse(responseCode = "200", description = "OK"),
         @ApiResponse(responseCode = "400", description = "Bad Request", content = {@Content(mediaType = "application/json", schema = @Schema(implementation = ApiErrorResponse.class))}),