add better swagger docs with examples

This commit is contained in:
Lee 2024-04-10 10:26:24 +01:00
parent 708ccc294d
commit 3bd0ea3838
2 changed files with 21 additions and 6 deletions

@ -4,6 +4,7 @@ import cc.fascinated.common.PlayerUtils;
import cc.fascinated.model.player.Player; import cc.fascinated.model.player.Player;
import cc.fascinated.model.player.Skin; import cc.fascinated.model.player.Skin;
import cc.fascinated.service.PlayerService; import cc.fascinated.service.PlayerService;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag; import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.CacheControl; import org.springframework.http.CacheControl;
@ -29,15 +30,21 @@ public class PlayerController {
@ResponseBody @ResponseBody
@GetMapping(value = "/{id}", produces = MediaType.APPLICATION_JSON_VALUE) @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() return ResponseEntity.ok()
.cacheControl(cacheControl) .cacheControl(cacheControl)
.body(playerManagerService.getPlayer(id)); .body(playerManagerService.getPlayer(id));
} }
@GetMapping(value = "/{part}/{id}") @GetMapping(value = "/{part}/{id}")
public ResponseEntity<?> getPlayerHead(@PathVariable String part, 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, @PathVariable String id,
@Parameter(description = "The size of the image", example = "256")
@RequestParam(required = false, defaultValue = "256") int size) { @RequestParam(required = false, defaultValue = "256") int size) {
Player player = playerManagerService.getPlayer(id); Player player = playerManagerService.getPlayer(id);
Skin.Parts skinPart = Skin.Parts.fromName(part); Skin.Parts skinPart = Skin.Parts.fromName(part);

@ -4,6 +4,8 @@ import cc.fascinated.common.ServerUtils;
import cc.fascinated.common.Tuple; import cc.fascinated.common.Tuple;
import cc.fascinated.model.cache.CachedMinecraftServer; import cc.fascinated.model.cache.CachedMinecraftServer;
import cc.fascinated.service.ServerService; 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 io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders; import org.springframework.http.HttpHeaders;
@ -21,14 +23,20 @@ public class ServerController {
@ResponseBody @ResponseBody
@GetMapping(value = "/{platform}/{hostnameAndPort}", produces = MediaType.APPLICATION_JSON_VALUE) @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); Tuple<String, Integer> host = ServerUtils.getHostnameAndPort(hostnameAndPort);
return serverService.getServer(platform, host.getLeft(), host.getRight()); return serverService.getServer(platform, host.getLeft(), host.getRight());
} }
@ResponseBody @ResponseBody
@GetMapping(value = "/icon/{hostnameAndPort}", produces = MediaType.APPLICATION_JSON_VALUE) @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); Tuple<String, Integer> host = ServerUtils.getHostnameAndPort(hostnameAndPort);
String hostname = host.getLeft(); String hostname = host.getLeft();
int port = host.getRight(); int port = host.getRight();