chore: update @tag descriptions

l3s-learnweb · Aug 7, 2024 · c7c15dd · c7c15dd
1 parent 9022c69
commit c7c15dd
Show file tree

Hide file tree

Showing 8 changed files with 21 additions and 19 deletions.
diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/InterwebApplication.java b/interweb-server/src/main/java/de/l3s/interweb/server/InterwebApplication.java
@@ -14,9 +14,9 @@
     info = @Info(
         title = "Interweb API",
         version = "4.0.0",
+        description = "Unified API for Information Retrieval.",
         contact = @Contact(
             name = "Learnweb Team",
-            url = "https://learnweb.l3s.uni-hannover.de/lw/contact.jsf",
             email = "[email protected]"),
         license = @License(name = "The MIT License", url = "https://opensource.org/licenses/MIT")
     ),

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/chat/ChatResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/chat/ChatResource.java
@@ -14,13 +14,16 @@
 import io.quarkus.security.identity.SecurityIdentity;
 import io.smallrye.mutiny.Multi;
 import io.smallrye.mutiny.Uni;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.hibernate.reactive.mutiny.Mutiny;
 
 import de.l3s.interweb.core.chat.*;
 import de.l3s.interweb.core.util.StringUtils;
 import de.l3s.interweb.server.features.user.Token;
 
+@Tag(name = "Chat")
 @Path("/chat")
+@Authenticated
 public class ChatResource {
 
     @Inject
@@ -30,7 +33,6 @@ public class ChatResource {
     SecurityIdentity securityIdentity;
 
     @GET
-    @Authenticated
     public Uni<List<Chat>> chats(
         @QueryParam("user") String user,
         @QueryParam("sort") @DefaultValue("-created") String order,
@@ -63,7 +65,6 @@ private static Uni<List<ChatMessage>> createChatTitle(Chat chat) {
     }
 
     @GET
-    @Authenticated
     @Path("{uuid}")
     public Uni<Conversation> chat(@PathParam("uuid") UUID id) {
         Token token = securityIdentity.getCredential(Token.class);
@@ -81,7 +82,6 @@ public Uni<Conversation> chat(@PathParam("uuid") UUID id) {
     }
 
     @POST
-    @Authenticated
     @Path("/completions")
     public Uni<CompletionsResults> completions(@Valid CompletionsQuery query) {
         Token token = securityIdentity.getCredential(Token.class);

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/describe/DescribeResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/describe/DescribeResource.java
@@ -3,7 +3,6 @@
 import java.util.ArrayList;
 import java.util.List;
 
-import jakarta.annotation.security.PermitAll;
 import jakarta.inject.Inject;
 import jakarta.validation.Valid;
 import jakarta.validation.ValidationException;
@@ -14,21 +13,23 @@
 import io.quarkus.cache.CacheResult;
 import io.quarkus.security.Authenticated;
 import io.smallrye.mutiny.Uni;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.jboss.resteasy.reactive.RestQuery;
 
 import de.l3s.interweb.core.describe.DescribeConnector;
 import de.l3s.interweb.core.describe.DescribeQuery;
 import de.l3s.interweb.core.describe.DescribeResults;
 import de.l3s.interweb.core.util.StringUtils;
 
+@Tag(name = "Describe", description = "Retrieve information about a resource (URL)")
 @Path("/describe")
+@Authenticated
 public class DescribeResource {
 
     @Inject
     DescribeService describeService;
 
     @GET
-    @Authenticated
     public Uni<DescribeResults> describe(@RestQuery String link,
                                          @RestQuery String id,
                                          @RestQuery String services) {
@@ -42,7 +43,6 @@ public Uni<DescribeResults> describe(@RestQuery String link,
     }
 
     @POST
-    @Authenticated
     @CacheResult(cacheName = "describe")
     public Uni<DescribeResults> describe(@Valid DescribeQuery query) {
         describeService.validateServices(query.getServices());
@@ -56,7 +56,6 @@ public Uni<DescribeResults> describe(@Valid DescribeQuery query) {
     }
 
     @GET
-    @PermitAll
     @Path("/services")
     public Uni<List<ServiceEntity>> services() {
         List<ServiceEntity> services = new ArrayList<>();

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/models/ModelsResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/models/ModelsResource.java
@@ -9,24 +9,25 @@
 
 import io.quarkus.security.Authenticated;
 import io.smallrye.mutiny.Uni;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import de.l3s.interweb.core.ObjectWrapper;
 import de.l3s.interweb.core.models.Model;
 
+@Tag(name = "Models", description = "List all available models")
 @Path("/models")
+@Authenticated
 public class ModelsResource {
 
     @Inject
     ModelsService modelsService;
 
     @GET
-    @Authenticated
     public Uni<ObjectWrapper<List<Model>>> models() {
         return modelsService.getModels().map(models -> new ObjectWrapper<>("list", models));
     }
 
     @GET
-    @Authenticated
     @Path("{model}")
     public Uni<Model> chat(@PathParam("model") String model) {
         return modelsService.getModel(model);

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/search/SearchResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/search/SearchResource.java
@@ -21,12 +21,15 @@
 import io.quarkus.security.identity.SecurityIdentity;
 import io.smallrye.mutiny.Uni;
 import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.jboss.resteasy.reactive.RestQuery;
 
 import de.l3s.interweb.core.search.*;
 import de.l3s.interweb.core.util.StringUtils;
 
+@Tag(name = "Search", description = "Search internet by query")
 @Path("/search")
+@Authenticated
 public class SearchResource {
     private static final String NO_CACHE = "no-cache";
 
@@ -37,7 +40,6 @@ public class SearchResource {
     SecurityIdentity securityIdentity;
 
     @GET
-    @Authenticated
     public Uni<SearchResults> search(@Parameter(description = "The search query", example = "hello world") @NotEmpty @RestQuery("query") String query,
                                      @Parameter(description = "A content types to search for") @NotEmpty @RestQuery("content_types") ContentType[] contentTypes,
                                      @Parameter(description = "A services to search in") @RestQuery("services") String[] services,
@@ -66,7 +68,6 @@ public Uni<SearchResults> search(@Parameter(description = "The search query", ex
     }
 
     @POST
-    @Authenticated
     public Uni<SearchResults> search(@NotNull @Valid SearchQuery query, @HeaderParam("Cache-Control") String cacheControl) {
         long start = System.currentTimeMillis();
         if (NO_CACHE.equals(cacheControl)) {

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/suggest/SuggestResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/suggest/SuggestResource.java
@@ -3,7 +3,6 @@
 import java.util.ArrayList;
 import java.util.List;
 
-import jakarta.annotation.security.PermitAll;
 import jakarta.inject.Inject;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;
@@ -15,21 +14,23 @@
 import io.quarkus.cache.CacheResult;
 import io.quarkus.security.Authenticated;
 import io.smallrye.mutiny.Uni;
+import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.jboss.resteasy.reactive.RestQuery;
 
 import de.l3s.interweb.core.suggest.SuggestConnector;
 import de.l3s.interweb.core.suggest.SuggestQuery;
 import de.l3s.interweb.core.suggest.SuggestResults;
 import de.l3s.interweb.core.util.StringUtils;
 
+@Tag(name = "Suggest", description = "Suggest completions for a query")
 @Path("/suggest")
+@Authenticated
 public class SuggestResource {
 
     @Inject
     SuggestService suggestService;
 
     @GET
-    @Authenticated
     public Uni<SuggestResults> suggest(@NotEmpty @RestQuery String q,
                                        @Size(min = 2, max = 2) @RestQuery String lang,
                                        @RestQuery String services) {
@@ -45,7 +46,6 @@ public Uni<SuggestResults> suggest(@NotEmpty @RestQuery String q,
     }
 
     @POST
-    @Authenticated
     @CacheResult(cacheName = "suggest")
     public Uni<SuggestResults> suggest(@Valid SuggestQuery query) {
         long start = System.currentTimeMillis();
@@ -58,7 +58,6 @@ public Uni<SuggestResults> suggest(@Valid SuggestQuery query) {
     }
 
     @GET
-    @PermitAll
     @Path("/services")
     public Uni<List<ServiceEntity>> services() {
         List<ServiceEntity> services = new ArrayList<>();

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/user/TokenResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/user/TokenResource.java
@@ -12,15 +12,17 @@
 
 import io.quarkus.hibernate.reactive.panache.PanacheEntityBase;
 import io.quarkus.hibernate.reactive.panache.common.WithTransaction;
+import io.quarkus.security.Authenticated;
 import io.quarkus.security.identity.SecurityIdentity;
 import io.smallrye.mutiny.Uni;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 
 import de.l3s.interweb.server.Roles;
 
-@Path("/users/tokens")
-@Tag(name = "Tokens", description = "Use to create a new client with Api-Key auth.")
+@Tag(name = "API Keys", description = "Manage application access")
+@Path("/tokens")
+@Authenticated
 public class TokenResource {
 
     @Context

diff --git a/interweb-server/src/main/java/de/l3s/interweb/server/features/user/UserResource.java b/interweb-server/src/main/java/de/l3s/interweb/server/features/user/UserResource.java
@@ -19,10 +19,10 @@
 
 import de.l3s.interweb.server.Roles;
 
+@Tag(name = "Auth & Identity", description = "User management")
 @Path("/")
 @Consumes(MediaType.APPLICATION_JSON)
 @Produces(MediaType.APPLICATION_JSON)
-@Tag(name = "Identity", description = "Identity & tokens management")
 public class UserResource {
 
     @Context