From e9ccb15b4e3d1a961e605a819f1b3c43cc367b57 Mon Sep 17 00:00:00 2001 From: Jari Date: Sun, 19 Oct 2025 15:39:19 +0200 Subject: [PATCH] =?UTF-8?q?swaggeri=C3=B1o=202?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../octopus/internal/common/models/Entry.kt | 11 +++++ .../web/controllers/EntryController.kt | 40 ++++++++++++++++++- .../internal/web/utils/dtos/EntryDto.kt | 18 +++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) diff --git a/src/main/kotlin/org/octopus/internal/common/models/Entry.kt b/src/main/kotlin/org/octopus/internal/common/models/Entry.kt index f9ed569..6a36b48 100755 --- a/src/main/kotlin/org/octopus/internal/common/models/Entry.kt +++ b/src/main/kotlin/org/octopus/internal/common/models/Entry.kt @@ -2,21 +2,32 @@ package org.octopus.internal.common.models import com.fasterxml.jackson.annotation.JsonGetter import com.fasterxml.jackson.annotation.JsonIgnore +import io.swagger.v3.oas.annotations.media.Schema import org.octopus.internal.common.enums.EEntryType import java.time.Month import java.util.* data class Entry( + @field:Schema(description = "The id of the entry in the DB") var id: Long?, + @field:Schema(description = "The name of the entry (between 1 and 50 characters long).") val name: String, + @field:Schema(description = "The type of entry (INCOME, OUTCOME, INVESTMENT).") val type: EEntryType, + @field:Schema(description = "The amount of the entry (greater than 0.00).") val amount: Double, + @field:Schema(description = "IF NOT recurrent: when is the entry being counted.") val fixedDate: Date? = null, + @field:Schema(description = "IF recurrent: must be true") val recurrent: Boolean? = false, + @field:Schema(description = "IF recurrent: list of month in which the event is repeated (1=JAN, 12=DEC)") @get:JsonIgnore val recurrentMonths: List? = mutableListOf(), + @field:Schema(description = "IF recurrent: starting date of the repetition") val startDate: Date? = null, + @field:Schema(description = "IF recurrent: ending date of the repetition") val endDate: Date? = null, + @field:Schema(description = "Color of the entry in the UI") val color: String ){ diff --git a/src/main/kotlin/org/octopus/internal/web/controllers/EntryController.kt b/src/main/kotlin/org/octopus/internal/web/controllers/EntryController.kt index 1ddb67c..99fab93 100755 --- a/src/main/kotlin/org/octopus/internal/web/controllers/EntryController.kt +++ b/src/main/kotlin/org/octopus/internal/web/controllers/EntryController.kt @@ -1,5 +1,8 @@ package org.octopus.internal.web.controllers +import io.swagger.v3.oas.annotations.Operation +import io.swagger.v3.oas.annotations.responses.ApiResponse +import io.swagger.v3.oas.annotations.tags.Tag import jakarta.validation.Valid import lombok.AllArgsConstructor import org.octopus.internal.common.models.Entry @@ -12,10 +15,17 @@ import org.springframework.web.bind.annotation.* @RestController @RequestMapping("/entries") @AllArgsConstructor +@Tag(name = "Entries Management", description = "Operations related to entries.") class EntryController( val entryService: EntryService ) { - + @Operation( + summary = "Create a new planning entry", + description = "Adds a new income, outcome, or investment entry to the system.", + responses = [ + ApiResponse(responseCode = "200", description = "Entry created successfully. Returned with ID") + ] + ) @PostMapping fun createEntry( @Valid @RequestBody entryDto: EntryDto @@ -23,21 +33,49 @@ class EntryController( return WebResponse.ok(entryService.createEntry(entryDto)) } + @Operation( + summary = "Get all entries in the DB", + description = "Returns a list containing all entries.", + responses = [ + ApiResponse(responseCode = "200", description = "A valid list.") + ] + ) @GetMapping fun getAllEntries(): WebResponse> { return WebResponse.ok(entryService.getAllEntries()) } + @Operation( + summary = "Delete all entries in the DB", + description = "Returns the result of the operation.", + responses = [ + ApiResponse(responseCode = "200", description = "Whether the operation succeeded.") + ] + ) @DeleteMapping fun deleteAllEntries(): WebResponse { return WebResponse.ok(entryService.deleteAll()) } + @Operation( + summary = "Delete a specific entry in the DB", + description = "Returns the result of the operation.", + responses = [ + ApiResponse(responseCode = "200", description = "Whether the operation succeeded.") + ] + ) @DeleteMapping("/{id}") fun deleteEntryById(@PathVariable("id") id: Long): WebResponse { return WebResponse.ok(entryService.deleteById(id)) } + @Operation( + summary = "Updates a specific entry in the DB", + description = "Returns the updated entry.", + responses = [ + ApiResponse(responseCode = "200", description = "The updated entry.") + ] + ) @PutMapping("/{id}") fun editEntryById(@PathVariable("id") id: Long, @Valid @RequestBody entryDto: EntryDto): WebResponse { diff --git a/src/main/kotlin/org/octopus/internal/web/utils/dtos/EntryDto.kt b/src/main/kotlin/org/octopus/internal/web/utils/dtos/EntryDto.kt index 290c8ab..9e356fa 100755 --- a/src/main/kotlin/org/octopus/internal/web/utils/dtos/EntryDto.kt +++ b/src/main/kotlin/org/octopus/internal/web/utils/dtos/EntryDto.kt @@ -1,5 +1,6 @@ package org.octopus.internal.web.utils.dtos +import io.swagger.v3.oas.annotations.media.Schema import jakarta.validation.constraints.DecimalMin import org.hibernate.validator.constraints.Length import org.octopus.internal.web.utils.dtos.validators.EntryHexColorValidator @@ -8,18 +9,35 @@ import org.octopus.internal.web.utils.dtos.validators.EntryTypeValidator import java.util.Date data class EntryDto( + @field:Schema(description = "The name of the entry (between 1 and 50 characters long).") @field:Length(min = 1, max = 50, message = "The name must be between 1 and 50 characters long.") val name: String, + + @field:Schema(description = "The type of entry (INCOME, OUTCOME, INVESTMENT).") @field:EntryTypeValidator.Validate val type: String, + + @field:Schema(description = "The amount of the entry (greater than 0.00).") @field:DecimalMin(value="0.00", inclusive = false, message = "The amount must be greater than 0.00.") val amount: Double, + + @field:Schema(description = "IF NOT recurrent: when is the entry being counted.") val fixedDate: Date?, + + @field:Schema(description = "IF recurrent: must be true") val recurrent: Boolean?, + + @field:Schema(description = "IF recurrent: list of month in which the event is repeated (1=JAN, 12=DEC)") @field:EntryMonthValidator.Validate val recurrentMonths: List?, + + @field:Schema(description = "IF recurrent: starting date of the repetition") val startDate: Date?, + + @field:Schema(description = "IF recurrent: ending date of the repetition") val endDate: Date?, + + @field:Schema(description = "Color of the entry in the UI") @field:EntryHexColorValidator.Validate val color: String = "0xFFFFFF" ) \ No newline at end of file