From f651f417c14e3a22da1d3653db5e15ee2e8919de Mon Sep 17 00:00:00 2001
From: Arthur Wambst <wambst.arthur2@gmail.com>
Date: Tue, 19 Aug 2025 23:22:46 +0200
Subject: [PATCH] hints for site

---
 .../la_banquise/backend/rest/JiResource.java  |  1 +
 .../backend/rest/SiteEndpoints.java           | 36 ++++++++++++++++---
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/src/main/java/fr/la_banquise/backend/rest/JiResource.java b/src/main/java/fr/la_banquise/backend/rest/JiResource.java
index 39aba73..3fbb282 100644
--- a/src/main/java/fr/la_banquise/backend/rest/JiResource.java
+++ b/src/main/java/fr/la_banquise/backend/rest/JiResource.java
@@ -25,6 +25,7 @@ public class JiResource {
     @GET
     @Path("/listall")
     @Produces(MediaType.APPLICATION_JSON)
+    @RolesAllowed("root")
     public Response listall() {
         try {
             List<Ji> ji = jiService.getAllJiAdmin();
diff --git a/src/main/java/fr/la_banquise/backend/rest/SiteEndpoints.java b/src/main/java/fr/la_banquise/backend/rest/SiteEndpoints.java
index 0f9ed58..505b397 100644
--- a/src/main/java/fr/la_banquise/backend/rest/SiteEndpoints.java
+++ b/src/main/java/fr/la_banquise/backend/rest/SiteEndpoints.java
@@ -30,7 +30,15 @@ public class SiteEndpoints {
     @Path("/listall")
     @Produces(MediaType.APPLICATION_JSON)
     @RolesAllowed("root")
-    public Response listall() {
+    @Operation(summary = "Lists all existing sites",
+               description = "Lists all sites. Root role required.")
+    @APIResponses({
+        @APIResponse(responseCode = "200", description = "Successfull")
+        , @APIResponse(responseCode = "500",
+                       description = "Internal server error")
+    })
+    public Response
+    listall() {
         try {
             List<Site> sites = siteService.getAllSites();
             return Response.ok(sites).build();
@@ -44,9 +52,18 @@ public class SiteEndpoints {
     @POST
     @Path("/create")
     @RolesAllowed("root")
-    public Response createSite(@QueryParam("name") String name,
-                               @QueryParam("desc") String desc,
-                               @QueryParam("address") String address) {
+    @Operation(summary = "Creates a site",
+               description = "Creates a site if no name is not a duplicate.")
+    @APIResponses({
+        @APIResponse(responseCode = "200", description = "Successfully created")
+        , @APIResponse(
+              responseCode = "500",
+              description =
+                  "Internal server error, usually site name already taken")
+    })
+    public Response
+    createSite(@QueryParam("name") String name, @QueryParam("desc") String desc,
+               @QueryParam("address") String address) {
         try {
             String jsp = siteService.createSite(name, desc, address).toString();
             return Response.ok(Map.of("created", jsp)).build();
@@ -61,7 +78,16 @@ public class SiteEndpoints {
     @Path("/getbyname")
     @Produces(MediaType.APPLICATION_JSON)
     @Authenticated
-    public Response getSiteByName(@QueryParam("name") String name) {
+    @Operation(summary = "Gets a site with its name", description = "")
+    @APIResponses({
+        @APIResponse(responseCode = "200", description = "Site found")
+        , @APIResponse(responseCode = "500",
+                       description =
+                           "Internal server error, usually site not found")
+    })
+
+    public Response
+    getSiteByName(@QueryParam("name") String name) {
         try {
             Site site = siteService.getSiteByName(name);
             return Response.ok(site.toString()).build();