Skip to content

Add Swagger annotations to existing endpoints #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
theEvilReaper merged 2 commits into from
Jul 16, 2025
Merged

Add Swagger annotations to existing endpoints #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d419d0
Improve license information and add tag entry
theEvilReaper Jul 16, 2025
b7a6fca
Add swagger annotations
theEvilReaper Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions backend/src/main/java/net/onelitefeather/otis/OtisApplication.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,20 @@
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.tags.Tag;

@ConfigurationProperties("application.properties")
@OpenAPIDefinition(
info = @Info(
title = "Otis API",
version = "0.0.1",
description = "Simple user management system",
license = @License(name = "Close Source"),
license = @License(name = "Apache-2.0"),
contact = @Contact(url = "https://onelitefeather.net", name = "Management", email = "admin@onelitefeather.net")
)
),
tags = {
@Tag(name = "Player", description = "Player management"),
}
)
public class OtisApplication {

Expand Down
134 changes: 132 additions & 2 deletions backend/src/main/java/net/onelitefeather/otis/controller/OtisRequestsController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Post;
import io.micronaut.validation.Validated;
import io.swagger.v3.oas.annotations.Operation;
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 jakarta.inject.Inject;
import jakarta.validation.Valid;
import net.onelitefeather.otis.database.entity.OtisPlayer;
Expand All @@ -26,14 +30,56 @@ public OtisRequestsController(OtisPlayerRepository repository) {
this.repository = repository;
}

@Operation(
summary = "Add a new Otis player",
description = "This endpoint allows you to add a new Otis player to the database.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Player added successfully",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "500",
description = "The player could not be added to the database",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Validated
@Post()
@Post
public HttpResponse<OtisPlayerDTO> add(@Valid OtisPlayerDTO playerDTO) {
OtisPlayer otisPlayer = OtisPlayer.toEntity(playerDTO);
OtisPlayer saved = repository.save(otisPlayer);
return HttpResponse.ok(saved.toDto());
}

@Operation(
summary = "Get Otis player by ID",
description = "This endpoint retrieves an Otis player by their UUID.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Player was successfully found.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "Player not found",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Validated
@Get("/byId/{owner}")
public HttpResponse<OtisPlayerDTO> getById(@Valid UUID owner) {
Expand All @@ -44,6 +90,27 @@ public HttpResponse<OtisPlayerDTO> getById(@Valid UUID owner) {
return HttpResponse.ok(entity.toDto());
}

@Operation(
summary = "Get Otis player by name",
description = "This endpoint retrieves an Otis player by their name.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Player was successfully found.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "Player not found",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Validated
@Get("/byName/{owner}")
public HttpResponse<OtisPlayerDTO> getByString(@Valid String owner) {
Expand All @@ -54,6 +121,27 @@ public HttpResponse<OtisPlayerDTO> getByString(@Valid String owner) {
return HttpResponse.ok(entity.toDto());
}

@Operation(
summary = "Update an existing Otis player",
description = "This endpoint allows you to update an existing Otis player in the database.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Player updated successfully",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "400",
description = "Bad request, player UUID does not match the owner",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Validated
@Post("/update/{owner}")
public HttpResponse<OtisPlayerDTO> update(@Valid UUID owner, @Valid OtisPlayerDTO playerDTO) {
Expand All @@ -65,6 +153,27 @@ public HttpResponse<OtisPlayerDTO> update(@Valid UUID owner, @Valid OtisPlayerDT
return HttpResponse.ok(saved.toDto());
}

@Operation(
summary = "Delete an Otis player",
description = "This endpoint allows you to delete an Otis player from the database.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Player deleted successfully",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "Player not found",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Validated
@Post("/delete/{owner}")
public HttpResponse<OtisPlayerDTO> delete(@Valid UUID owner) {
Expand All @@ -82,7 +191,28 @@ public HttpResponse<OtisPlayerDTO> delete(@Valid UUID owner) {
* @param pageable the pageable instance
* @return a list of all players
*/
@Get("/all")
@Operation(
summary = "Get all Otis players",
description = "This endpoint retrieves all Otis players from the database.",
tags = {"Player"}
)
@ApiResponse(
responseCode = "200",
description = "Players retrieved successfully",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "No players found",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Get(uris = {"/getAll", "/all"})
public HttpResponse<Iterable<OtisPlayerDTO>> getAll(Pageable pageable) {
Page<OtisPlayer> entities = this.repository.findAll(pageable);
if (entities.isEmpty()) {
Expand Down
55 changes: 53 additions & 2 deletions backend/src/main/java/net/onelitefeather/otis/controller/OtisSearchController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.swagger.v3.oas.annotations.Operation;
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 jakarta.inject.Inject;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Pattern;
Expand All @@ -19,11 +23,37 @@ public class OtisSearchController {

private final OtisPlayerRepository otisPlayerRepository;

/**
* Constructs a new reference to the OtisSearchController.
*
* @param playerRepository the repository to access player data.
*/
@Inject
public OtisSearchController(OtisPlayerRepository otisPlayerRepository) {
this.otisPlayerRepository = otisPlayerRepository;
public OtisSearchController(OtisPlayerRepository playerRepository) {
this.otisPlayerRepository = playerRepository;
}

@Operation(
summary = "Search for a player by their ID",
description = "Returns the player information if found, otherwise returns 404 Not Found.",
tags = {"Player", "Search"}
)
@ApiResponse(
responseCode = "200",
description = "Player found and returned successfully.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "Player not found.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Valid
@Get("/byId/{id}")
public HttpResponse<OtisPlayerDTO> searchById(@Valid UUID id) {
Expand All @@ -36,6 +66,27 @@ public HttpResponse<OtisPlayerDTO> searchById(@Valid UUID id) {
return HttpResponse.ok(entity.get().toDto());
}

@Operation(
summary = "Search for a player by their name",
description = "Returns the player information if found, otherwise returns 404 Not Found.",
tags = {"Player", "Search"}
)
@ApiResponse(
responseCode = "200",
description = "Player found and returned successfully.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = OtisPlayerDTO.class)
)
)
@ApiResponse(
responseCode = "404",
description = "Player not found.",
content = @Content(
mediaType = "application/json",
schema = @Schema(implementation = String.class)
)
)
@Valid
@Get("/byName/{name}")
public HttpResponse<OtisPlayerDTO> searchByName(
Expand Down
Loading