From 3bd0ea3838c0d2f87cc89375874acfdf0a642f11 Mon Sep 17 00:00:00 2001 From: Liam 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 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 host = ServerUtils.getHostnameAndPort(hostnameAndPort); String hostname = host.getLeft(); int port = host.getRight();