From 3bd0ea3838c0d2f87cc89375874acfdf0a642f11 Mon Sep 17 00:00:00 2001
From: Liam <liam@fascinated.cc>
Date: Wed, 10 Apr 2024 10:26:24 +0100
Subject: [PATCH] add better swagger docs with examples

---
 .../controller/PlayerController.java              | 15 +++++++++++----
 .../controller/ServerController.java              | 12 ++++++++++--
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/src/main/java/cc.fascinated/controller/PlayerController.java b/src/main/java/cc.fascinated/controller/PlayerController.java
index a2fcc1c..7228556 100644
--- a/src/main/java/cc.fascinated/controller/PlayerController.java
+++ b/src/main/java/cc.fascinated/controller/PlayerController.java
@@ -4,6 +4,7 @@ import cc.fascinated.common.PlayerUtils;
 import cc.fascinated.model.player.Player;
 import cc.fascinated.model.player.Skin;
 import cc.fascinated.service.PlayerService;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.CacheControl;
@@ -29,16 +30,22 @@ public class PlayerController {
 
     @ResponseBody
     @GetMapping(value = "/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
-    public ResponseEntity<?> getPlayer(@PathVariable String id) {
+    public ResponseEntity<?> getPlayer(
+            @Parameter(description = "The UUID or Username of the player", example = "ImFascinated")
+            @PathVariable String id) {
         return ResponseEntity.ok()
                 .cacheControl(cacheControl)
                 .body(playerManagerService.getPlayer(id));
     }
 
     @GetMapping(value = "/{part}/{id}")
-    public ResponseEntity<?> getPlayerHead(@PathVariable String part,
-                                                @PathVariable String id,
-                                                @RequestParam(required = false, defaultValue = "256") int size) {
+    public ResponseEntity<?> getPlayerHead(
+            @Parameter(description = "The part of the skin", example = "head")
+            @PathVariable String part,
+            @Parameter(description = "The UUID or Username of the player", example = "ImFascinated")
+            @PathVariable String id,
+            @Parameter(description = "The size of the image", example = "256")
+            @RequestParam(required = false, defaultValue = "256") int size) {
         Player player = playerManagerService.getPlayer(id);
         Skin.Parts skinPart = Skin.Parts.fromName(part);
 
diff --git a/src/main/java/cc.fascinated/controller/ServerController.java b/src/main/java/cc.fascinated/controller/ServerController.java
index 59ced98..549ad3d 100644
--- a/src/main/java/cc.fascinated/controller/ServerController.java
+++ b/src/main/java/cc.fascinated/controller/ServerController.java
@@ -4,6 +4,8 @@ import cc.fascinated.common.ServerUtils;
 import cc.fascinated.common.Tuple;
 import cc.fascinated.model.cache.CachedMinecraftServer;
 import cc.fascinated.service.ServerService;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpHeaders;
@@ -21,14 +23,20 @@ public class ServerController {
 
     @ResponseBody
     @GetMapping(value = "/{platform}/{hostnameAndPort}", produces = MediaType.APPLICATION_JSON_VALUE)
-    public CachedMinecraftServer getServer(@PathVariable String platform, @PathVariable String hostnameAndPort) {
+    public CachedMinecraftServer getServer(
+            @Parameter(description = "The platform of the server", example = "java")
+            @PathVariable String platform,
+            @Parameter(description = "The hostname and port of the server", example = "play.hypixel.net")
+            @PathVariable String hostnameAndPort) {
         Tuple<String, Integer> host = ServerUtils.getHostnameAndPort(hostnameAndPort);
         return serverService.getServer(platform, host.getLeft(), host.getRight());
     }
 
     @ResponseBody
     @GetMapping(value = "/icon/{hostnameAndPort}", produces = MediaType.APPLICATION_JSON_VALUE)
-    public ResponseEntity<?> getServerIcon(@PathVariable String hostnameAndPort) {
+    public ResponseEntity<?> getServerIcon(
+            @Parameter(description = "The hostname and port of the server", example = "play.hypixel.net")
+            @PathVariable String hostnameAndPort) {
         Tuple<String, Integer> host = ServerUtils.getHostnameAndPort(hostnameAndPort);
         String hostname = host.getLeft();
         int port = host.getRight();