some swagger documentation

src/main/java/cz/trailsthroughshadows/api/debug/DebugController.java

@@ -1,4 +1,9 @@
 package cz.trailsthroughshadows.api.debug;
+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.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.io.Resource;
@@ -19,8 +24,31 @@ public class DebugController {
     @Autowired
     private ResourceLoader resourceLoader;
 
+    @Operation(
+            summary = "Get Latest Logs",
+            description = """
+                    # Get Latest Logs
+                    Retrieves the latest entries from the system's log file up to a specified number of characters. This endpoint is useful for quickly accessing recent log data without needing to download or search through the entire log file.
+
+                    **Parameters**:
+                    - `characters` - Optional. Specifies the maximum number of characters to retrieve from the end of the log file. Defaults to 50000 characters.
+
+                    This endpoint is particularly useful for developers and system administrators for monitoring and troubleshooting purposes.
+                    """
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Log entries successfully retrieved",
+                    content = {@Content(mediaType = "text/plain")}),
+            @ApiResponse(responseCode = "500", description = "Error reading log file",
+                    content = @Content),
+            @ApiResponse(responseCode = "default", description = "Unexpected error",
+                    content = @Content)
+    })
     @GetMapping("/logs/latest")
-    public String getLatestLogs(@RequestParam(required = false, defaultValue = "50000") int characters) throws IOException {
+    public String getLatestLogs(
+            @Parameter(description = "The maximum number of characters from the log file to retrieve. If not specified, defaults to 50000 characters.", required = false)
+            @RequestParam(required = false, defaultValue = "50000") int characters
+    ) throws IOException {
         String currDir = System.getProperty("user.dir");
         String path = currDir + "/logs/latest.log";
         Resource resource = resourceLoader.getResource("file:" + path);

src/main/java/cz/trailsthroughshadows/api/images/ImageController.java

@@ -1,6 +1,12 @@
 package cz.trailsthroughshadows.api.images;
 
 import cz.trailsthroughshadows.api.configuration.ImageLoaderConfig;
+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;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.cache.annotation.Cacheable;
@@ -28,16 +34,53 @@ public class ImageController {
     private ResourceLoader resourceLoader;
 
 
+    @Operation(
+            summary = "Retrieve Customizable Image",
+            description = """
+                    # Retrieve Customizable Image
+                    Fetches an image based on specified parameters allowing for dynamic customization. This endpoint caters to various needs by providing options to adjust the size, apply rounding to corners, and select specific image types or tokens.
+
+                    **Parameters**:
+                    - `type` - The category or collection to which the image belongs.
+                    - `file` - The specific file name of the image to retrieve.
+                    - `width` - Optional. The desired width to which the image should be resized.
+                    - `height` - Optional. The desired height to which the image should be resized.
+                    - `size` - Optional. A single value to resize the image to a square of specified dimensions.
+                    - `radius` - Optional, defaults to 0. Applies a radius to round the corners of the image.
+                    - `token` - Optional. A boolean that if set to true, fetches images from a token-specific path.
+
+                    This endpoint is designed to be flexible, supporting various image retrieval scenarios from adjusting dimensions to accessing specific types of images like tokens. If the requested image is not found, a default placeholder image is returned, potentially resized and rounded according to specified parameters. Image is in png format.
+                    """
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Image successfully retrieved",
+                    content = {@Content(mediaType = "image/png", // Assume PNG, adjust as necessary
+                            schema = @Schema(type = "string", format = "binary"))}),
+            @ApiResponse(responseCode = "404", description = "Image not found",
+                    content = @Content),
+            @ApiResponse(responseCode = "500", description = "Error processing image request",
+                    content = @Content),
+            @ApiResponse(responseCode = "default", description = "Unexpected error",
+                    content = @Content)
+    })
     @GetMapping("/{type}/{file}")
     @Cacheable(value = "image", key = "T(java.util.Objects).hash(#type, #file, #width, #height, #size, #radius, #token)")
     public @ResponseBody byte[] getImage(
+            @Parameter(description = "The category or collection to which the image belongs.", required = true)
             @PathVariable String type,
+            @Parameter(description = "The specific file name of the image to retrieve.", required = true)
             @PathVariable String file,
+            @Parameter(description = "The desired width to which the image should be resized. If not specified, the image will be returned in its original size.", required = false)
             @RequestParam(required = false) Integer width,
+            @Parameter(description = "The desired height to which the image should be resized. If not specified, the image will be returned in its original size.", required = false)
             @RequestParam(required = false) Integer height,
+            @Parameter(description = "A single value to resize the image to a square of specified dimensions. Overrides individual width/height settings if provided.", required = false)
             @RequestParam(required = false) Integer size,
+            @Parameter(description = "Applies a radius to round the corners of the image, given in pixels. Defaults to 0, meaning no rounding.", required = false)
             @RequestParam(required = false, defaultValue = "0") Integer radius,
-            @RequestParam(required = false) boolean token) throws IOException {
+            @Parameter(description = "A boolean indicating if the image should be retrieved from a token-specific path. Useful for token images in games.", required = false)
+            @RequestParam(required = false) boolean token
+    ) throws IOException {
 
         String localpath = type + "/" + ((token) ? "tokens/" : "") + file;
         var physicalPath = config.getPath();
@@ -80,10 +123,34 @@ public class ImageController {
 
     }
 
+    @Operation(
+            summary = "Retrieve SVG File",
+            description = """
+                    # Retrieve SVG File
+                    Fetches a scalable vector graphics (SVG) file based on a specified type and file name. This endpoint is designed to serve SVG files, which are ideal for high-quality graphics that need to be scalable without loss of resolution.
+
+                    **Parameters**:
+                    - `type` - The category or collection to which the SVG file belongs.
+                    - `file` - The specific file name of the SVG file to retrieve. The file name must include the '.svg' extension.
+
+                    This method ensures that SVG files are easily accessible and can be retrieved dynamically based on their type and name. This is particularly useful for applications requiring high-quality graphic representations that are scalable.
+                    """
+    )
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "SVG file successfully retrieved",
+                    content = {@Content(mediaType = "image/svg+xml",
+                            schema = @Schema(type = "string", format = "binary"))}),
+            @ApiResponse(responseCode = "404", description = "SVG file not found",
+                    content = @Content),
+            @ApiResponse(responseCode = "default", description = "Unexpected error",
+                    content = @Content)
+    })
     @GetMapping(value = "/svg/{type}/{file:.+\\.svg}")
     @Cacheable(value = "svg", key = "T(java.util.Objects).hash(#type, #file)")
-    public ResponseEntity<Resource> getSwg(
+    public ResponseEntity<Resource> getSvg(
+            @Parameter(description = "The category or collection to which the SVG file belongs.", required = true)
             @PathVariable String type,
+            @Parameter(description = "The specific file name of the SVG file to retrieve, including the '.svg' extension.", required = true)
             @PathVariable String file
     ) throws IOException {