Skip to content

Commit 426410c

Browse files
theEvilReapertheEvilReaper
authored
Merge pull request #21 from OneLiteFeatherNET/feature/openApi
Add Swagger annotations to existing endpoints
2 parents 832a984 + b7a6fca commit 426410c

File tree

3 files changed

+191
-6
lines changed

3 files changed

+191
-6
lines changed

‎backend/src/main/java/net/onelitefeather/otis/OtisApplication.java‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,20 @@
66
import io.swagger.v3.oas.annotations.info.Contact;
77
import io.swagger.v3.oas.annotations.info.Info;
88
import io.swagger.v3.oas.annotations.info.License;
9+
import io.swagger.v3.oas.annotations.tags.Tag;
910

1011
@ConfigurationProperties("application.properties")
1112
@OpenAPIDefinition(
1213
info = @Info(
1314
title = "Otis API",
1415
version = "0.0.1",
1516
description = "Simple user management system",
16-
license = @License(name = "Close Source"),
17+
license = @License(name = "Apache-2.0"),
1718
contact = @Contact(url = "https://onelitefeather.net", name = "Management", email = "admin@onelitefeather.net")
18-
)
19+
),
20+
tags = {
21+
@Tag(name = "Player", description = "Player management"),
22+
}
1923
)
2024
public class OtisApplication {
2125

‎backend/src/main/java/net/onelitefeather/otis/controller/OtisRequestsController.java‎

Lines changed: 132 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
import io.micronaut.http.annotation.Get;
88
import io.micronaut.http.annotation.Post;
99
import io.micronaut.validation.Validated;
10+
import io.swagger.v3.oas.annotations.Operation;
11+
import io.swagger.v3.oas.annotations.media.Content;
12+
import io.swagger.v3.oas.annotations.media.Schema;
13+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
1014
import jakarta.inject.Inject;
1115
import jakarta.validation.Valid;
1216
import net.onelitefeather.otis.database.entity.OtisPlayer;
@@ -26,14 +30,56 @@ public OtisRequestsController(OtisPlayerRepository repository) {
2630
this.repository = repository;
2731
}
2832

33+
@Operation(
34+
summary = "Add a new Otis player",
35+
description = "This endpoint allows you to add a new Otis player to the database.",
36+
tags = {"Player"}
37+
)
38+
@ApiResponse(
39+
responseCode = "200",
40+
description = "Player added successfully",
41+
content = @Content(
42+
mediaType = "application/json",
43+
schema = @Schema(implementation = OtisPlayerDTO.class)
44+
)
45+
)
46+
@ApiResponse(
47+
responseCode = "500",
48+
description = "The player could not be added to the database",
49+
content = @Content(
50+
mediaType = "application/json",
51+
schema = @Schema(implementation = String.class)
52+
)
53+
)
2954
@Validated
30-
@Post()
55+
@Post
3156
public HttpResponse<OtisPlayerDTO> add(@Valid OtisPlayerDTO playerDTO) {
3257
OtisPlayer otisPlayer = OtisPlayer.toEntity(playerDTO);
3358
OtisPlayer saved = repository.save(otisPlayer);
3459
return HttpResponse.ok(saved.toDto());
3560
}
3661

62+
@Operation(
63+
summary = "Get Otis player by ID",
64+
description = "This endpoint retrieves an Otis player by their UUID.",
65+
tags = {"Player"}
66+
)
67+
@ApiResponse(
68+
responseCode = "200",
69+
description = "Player was successfully found.",
70+
content = @Content(
71+
mediaType = "application/json",
72+
schema = @Schema(implementation = OtisPlayerDTO.class)
73+
)
74+
)
75+
@ApiResponse(
76+
responseCode = "404",
77+
description = "Player not found",
78+
content = @Content(
79+
mediaType = "application/json",
80+
schema = @Schema(implementation = String.class)
81+
)
82+
)
3783
@Validated
3884
@Get("/byId/{owner}")
3985
public HttpResponse<OtisPlayerDTO> getById(@Valid UUID owner) {
@@ -44,6 +90,27 @@ public HttpResponse<OtisPlayerDTO> getById(@Valid UUID owner) {
4490
return HttpResponse.ok(entity.toDto());
4591
}
4692

93+
@Operation(
94+
summary = "Get Otis player by name",
95+
description = "This endpoint retrieves an Otis player by their name.",
96+
tags = {"Player"}
97+
)
98+
@ApiResponse(
99+
responseCode = "200",
100+
description = "Player was successfully found.",
101+
content = @Content(
102+
mediaType = "application/json",
103+
schema = @Schema(implementation = OtisPlayerDTO.class)
104+
)
105+
)
106+
@ApiResponse(
107+
responseCode = "404",
108+
description = "Player not found",
109+
content = @Content(
110+
mediaType = "application/json",
111+
schema = @Schema(implementation = String.class)
112+
)
113+
)
47114
@Validated
48115
@Get("/byName/{owner}")
49116
public HttpResponse<OtisPlayerDTO> getByString(@Valid String owner) {
@@ -54,6 +121,27 @@ public HttpResponse<OtisPlayerDTO> getByString(@Valid String owner) {
54121
return HttpResponse.ok(entity.toDto());
55122
}
56123

124+
@Operation(
125+
summary = "Update an existing Otis player",
126+
description = "This endpoint allows you to update an existing Otis player in the database.",
127+
tags = {"Player"}
128+
)
129+
@ApiResponse(
130+
responseCode = "200",
131+
description = "Player updated successfully",
132+
content = @Content(
133+
mediaType = "application/json",
134+
schema = @Schema(implementation = OtisPlayerDTO.class)
135+
)
136+
)
137+
@ApiResponse(
138+
responseCode = "400",
139+
description = "Bad request, player UUID does not match the owner",
140+
content = @Content(
141+
mediaType = "application/json",
142+
schema = @Schema(implementation = String.class)
143+
)
144+
)
57145
@Validated
58146
@Post("/update/{owner}")
59147
public HttpResponse<OtisPlayerDTO> update(@Valid UUID owner, @Valid OtisPlayerDTO playerDTO) {
@@ -65,6 +153,27 @@ public HttpResponse<OtisPlayerDTO> update(@Valid UUID owner, @Valid OtisPlayerDT
65153
return HttpResponse.ok(saved.toDto());
66154
}
67155

156+
@Operation(
157+
summary = "Delete an Otis player",
158+
description = "This endpoint allows you to delete an Otis player from the database.",
159+
tags = {"Player"}
160+
)
161+
@ApiResponse(
162+
responseCode = "200",
163+
description = "Player deleted successfully",
164+
content = @Content(
165+
mediaType = "application/json",
166+
schema = @Schema(implementation = OtisPlayerDTO.class)
167+
)
168+
)
169+
@ApiResponse(
170+
responseCode = "404",
171+
description = "Player not found",
172+
content = @Content(
173+
mediaType = "application/json",
174+
schema = @Schema(implementation = String.class)
175+
)
176+
)
68177
@Validated
69178
@Post("/delete/{owner}")
70179
public HttpResponse<OtisPlayerDTO> delete(@Valid UUID owner) {
@@ -82,7 +191,28 @@ public HttpResponse<OtisPlayerDTO> delete(@Valid UUID owner) {
82191
* @param pageable the pageable instance
83192
* @return a list of all players
84193
*/
85-
@Get("/all")
194+
@Operation(
195+
summary = "Get all Otis players",
196+
description = "This endpoint retrieves all Otis players from the database.",
197+
tags = {"Player"}
198+
)
199+
@ApiResponse(
200+
responseCode = "200",
201+
description = "Players retrieved successfully",
202+
content = @Content(
203+
mediaType = "application/json",
204+
schema = @Schema(implementation = OtisPlayerDTO.class)
205+
)
206+
)
207+
@ApiResponse(
208+
responseCode = "404",
209+
description = "No players found",
210+
content = @Content(
211+
mediaType = "application/json",
212+
schema = @Schema(implementation = String.class)
213+
)
214+
)
215+
@Get(uris = {"/getAll", "/all"})
86216
public HttpResponse<Iterable<OtisPlayerDTO>> getAll(Pageable pageable) {
87217
Page<OtisPlayer> entities = this.repository.findAll(pageable);
88218
if (entities.isEmpty()) {

‎backend/src/main/java/net/onelitefeather/otis/controller/OtisSearchController.java‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
import io.micronaut.http.HttpResponse;
44
import io.micronaut.http.annotation.Controller;
55
import io.micronaut.http.annotation.Get;
6+
import io.swagger.v3.oas.annotations.Operation;
7+
import io.swagger.v3.oas.annotations.media.Content;
8+
import io.swagger.v3.oas.annotations.media.Schema;
9+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
610
import jakarta.inject.Inject;
711
import jakarta.validation.Valid;
812
import jakarta.validation.constraints.Pattern;
@@ -19,11 +23,37 @@ public class OtisSearchController {
1923

2024
private final OtisPlayerRepository otisPlayerRepository;
2125

26+
/**
27+
* Constructs a new reference to the OtisSearchController.
28+
*
29+
* @param playerRepository the repository to access player data.
30+
*/
2231
@Inject
23-
public OtisSearchController(OtisPlayerRepository otisPlayerRepository) {
24-
this.otisPlayerRepository = otisPlayerRepository;
32+
public OtisSearchController(OtisPlayerRepository playerRepository) {
33+
this.otisPlayerRepository = playerRepository;
2534
}
2635

36+
@Operation(
37+
summary = "Search for a player by their ID",
38+
description = "Returns the player information if found, otherwise returns 404 Not Found.",
39+
tags = {"Player", "Search"}
40+
)
41+
@ApiResponse(
42+
responseCode = "200",
43+
description = "Player found and returned successfully.",
44+
content = @Content(
45+
mediaType = "application/json",
46+
schema = @Schema(implementation = OtisPlayerDTO.class)
47+
)
48+
)
49+
@ApiResponse(
50+
responseCode = "404",
51+
description = "Player not found.",
52+
content = @Content(
53+
mediaType = "application/json",
54+
schema = @Schema(implementation = String.class)
55+
)
56+
)
2757
@Valid
2858
@Get("/byId/{id}")
2959
public HttpResponse<OtisPlayerDTO> searchById(@Valid UUID id) {
@@ -36,6 +66,27 @@ public HttpResponse<OtisPlayerDTO> searchById(@Valid UUID id) {
3666
return HttpResponse.ok(entity.get().toDto());
3767
}
3868

69+
@Operation(
70+
summary = "Search for a player by their name",
71+
description = "Returns the player information if found, otherwise returns 404 Not Found.",
72+
tags = {"Player", "Search"}
73+
)
74+
@ApiResponse(
75+
responseCode = "200",
76+
description = "Player found and returned successfully.",
77+
content = @Content(
78+
mediaType = "application/json",
79+
schema = @Schema(implementation = OtisPlayerDTO.class)
80+
)
81+
)
82+
@ApiResponse(
83+
responseCode = "404",
84+
description = "Player not found.",
85+
content = @Content(
86+
mediaType = "application/json",
87+
schema = @Schema(implementation = String.class)
88+
)
89+
)
3990
@Valid
4091
@Get("/byName/{name}")
4192
public HttpResponse<OtisPlayerDTO> searchByName(

0 commit comments

Comments
 (0)