From a4a34863416e3b79f23fb6a2bcbfaf9c87fce65e Mon Sep 17 00:00:00 2001
From: Rainnny7 <braydonrainnny@gmail.com>
Date: Wed, 10 Apr 2024 06:12:05 -0400
Subject: [PATCH] Swagger docs

---
 .../braydon/mc/controller/PlayerController.java  | 13 +++++++++----
 .../braydon/mc/controller/ServerController.java  | 16 ++++++++++++----
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/src/main/java/me/braydon/mc/controller/PlayerController.java b/src/main/java/me/braydon/mc/controller/PlayerController.java
index 2400d35..f21b910 100644
--- a/src/main/java/me/braydon/mc/controller/PlayerController.java
+++ b/src/main/java/me/braydon/mc/controller/PlayerController.java
@@ -23,6 +23,7 @@
  */
 package me.braydon.mc.controller;
 
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.NonNull;
 import lombok.extern.log4j.Log4j2;
@@ -69,8 +70,9 @@ public final class PlayerController {
      */
     @GetMapping("/{query}")
     @ResponseBody
-    public ResponseEntity<CachedPlayer> getPlayer(@PathVariable @NonNull String query)
-            throws BadRequestException, ResourceNotFoundException, MojangRateLimitException {
+    public ResponseEntity<CachedPlayer> getPlayer(
+            @Parameter(description = "The player username or UUID to get", example = "Rainnny") @PathVariable @NonNull String query
+    ) throws BadRequestException, ResourceNotFoundException, MojangRateLimitException {
         return ResponseEntity.ofNullable(mojangService.getPlayer(query, false));
     }
 
@@ -92,8 +94,11 @@ public final class PlayerController {
      */
     @GetMapping(value = "/{partName}/{query}.{extension}", produces = { MediaType.IMAGE_PNG_VALUE, MediaType.IMAGE_JPEG_VALUE })
     @ResponseBody
-    public ResponseEntity<byte[]> getPartTexture(@PathVariable @NonNull String partName, @PathVariable @NonNull String query,
-                                                 @PathVariable @NonNull String extension, @RequestParam(required = false) String size
+    public ResponseEntity<byte[]> getPartTexture(
+            @Parameter(description = "The skin part to get the texture of", example = "head") @PathVariable @NonNull String partName,
+            @Parameter(description = "The player username or UUID to get", example = "Rainnny") @PathVariable @NonNull String query,
+            @Parameter(description = "The image extension", example = "png") @PathVariable @NonNull String extension,
+            @Parameter(description = "The size to scale the skin part texture to", example = "256") @RequestParam(required = false) String size
     ) throws BadRequestException {
         return ResponseEntity.ok()
                 .contentType(extension.equalsIgnoreCase("png") ? MediaType.IMAGE_PNG : MediaType.IMAGE_JPEG)
diff --git a/src/main/java/me/braydon/mc/controller/ServerController.java b/src/main/java/me/braydon/mc/controller/ServerController.java
index 7760719..5b02efa 100644
--- a/src/main/java/me/braydon/mc/controller/ServerController.java
+++ b/src/main/java/me/braydon/mc/controller/ServerController.java
@@ -23,6 +23,7 @@
  */
 package me.braydon.mc.controller;
 
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.NonNull;
 import lombok.extern.log4j.Log4j2;
@@ -72,8 +73,10 @@ public final class ServerController {
      */
     @GetMapping("/{platform}/{hostname}")
     @ResponseBody
-    public ResponseEntity<CachedMinecraftServer> getServer(@PathVariable @NonNull String platform, @PathVariable @NonNull String hostname,
-                                                           @RequestParam(required = false) String port
+    public ResponseEntity<CachedMinecraftServer> getServer(
+            @Parameter(description = "The platform of the server", example = "java") @PathVariable @NonNull String platform,
+            @Parameter(description = "The hostname of the server", example = "hypixel.net") @PathVariable @NonNull String hostname,
+            @Parameter(description = "The port of the server", example = "25565") @RequestParam(required = false) String port
     ) throws BadRequestException, ResourceNotFoundException {
         return ResponseEntity.ofNullable(mojangService.getMinecraftServer(platform, hostname, port));
     }
@@ -87,7 +90,9 @@ public final class ServerController {
      */
     @GetMapping("/blocked/{hostname}")
     @ResponseBody
-    public ResponseEntity<Map<String, Object>> isServerBlocked(@PathVariable @NonNull String hostname) {
+    public ResponseEntity<Map<String, Object>> isServerBlocked(
+            @Parameter(description = "The hostname of the server", example = "hypixel.net") @PathVariable @NonNull String hostname
+    ) {
         return ResponseEntity.ok(Map.of(
                 "blocked", mojangService.isServerBlocked(hostname)
         ));
@@ -103,7 +108,10 @@ public final class ServerController {
      */
     @GetMapping(value = "/icon/{hostname}", produces = MediaType.IMAGE_PNG_VALUE)
     @ResponseBody
-    public ResponseEntity<byte[]> getServerFavicon(@PathVariable @NonNull String hostname, @RequestParam(required = false) String port) {
+    public ResponseEntity<byte[]> getServerFavicon(
+            @Parameter(description = "The hostname of the server", example = "hypixel.net") @PathVariable @NonNull String hostname,
+            @Parameter(description = "The port of the server", example = "25565") @RequestParam(required = false) String port
+    ) {
         return ResponseEntity.ok()
                 .contentType(MediaType.IMAGE_PNG)
                 .header(HttpHeaders.CONTENT_DISPOSITION, "inline; filename=%s.png".formatted(hostname))