Javadoc for the admin-client methods for the endpoints and parameters introduced since Keycloak 24

closes #32976

Signed-off-by: mposolda <mposolda@gmail.com>

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/AuthenticationManagementResource.java

@@ -179,20 +179,54 @@ public interface AuthenticationManagementResource {
     @POST
     void lowerRequiredActionPriority(@PathParam("alias") String alias);
 
+    /**
+     * Returns configuration description of the specified required action
+     *
+     * @since Keycloak server 25
+     * @param alias Alias of the required action, which configuration description will be returned
+     * @return Configuration description of the required action
+     * @throws jakarta.ws.rs.NotFoundException if the required action of specified alias is not found
+     */
     @Path("required-actions/{alias}/config-description")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     RequiredActionConfigInfoRepresentation getRequiredActionConfigDescription(@PathParam("alias") String alias);
 
+    /**
+     * Returns configuration of the specified required action
+     *
+     * @since Keycloak server 25
+     * @param alias Alias of the required action, which configuration will be returned
+     * @return Configuration of the required action
+     * @throws jakarta.ws.rs.BadRequestException if required action not configurable
+     * @throws jakarta.ws.rs.NotFoundException if the required action configuration of specified alias is not found
+     */
     @Path("required-actions/{alias}/config")
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     RequiredActionConfigRepresentation getRequiredActionConfig(@PathParam("alias") String alias);
 
+    /**
+     * Delete configuration of the specified required action
+     *
+     * @since Keycloak server 25
+     * @param alias Alias of the required action, which will be removed
+     * @throws jakarta.ws.rs.BadRequestException if required action not configurable
+     * @throws jakarta.ws.rs.NotFoundException if the required action configuration of specified alias is not found
+     */
     @Path("required-actions/{alias}/config")
     @DELETE
     void removeRequiredActionConfig(@PathParam("alias") String alias);
 
+    /**
+     * Update configuration of the required action
+     *
+     * @since Keycloak server 25
+     * @param alias Alias of the required action, which will be updated
+     * @param rep JSON representation of the required action
+     * @throws jakarta.ws.rs.BadRequestException if required action not configurable or given configuration is incorrect
+     * @throws jakarta.ws.rs.NotFoundException if the required action configuration of specified alias is not found
+     */
     @Path("required-actions/{alias}/config")
     @PUT
     @Consumes(MediaType.APPLICATION_JSON)

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/ClientPoliciesPoliciesResource.java

@@ -18,6 +18,12 @@ public interface ClientPoliciesPoliciesResource {
     @Produces(MediaType.APPLICATION_JSON)
     ClientPoliciesRepresentation getPolicies();
 
+    /**
+     * Get client policies for the realm.
+     *
+     * @param includeGlobalPolicies Indicates if global server clioent policies should be included or not. Parameter available since Keycloak server 25. Will be ignored on older Keycloak versions with the default value false
+     * @return client policies
+     */
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     ClientPoliciesRepresentation getPolicies(@QueryParam("include-global-policies") Boolean includeGlobalPolicies);

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/ClientTypesResource.java

@@ -26,6 +26,10 @@ import jakarta.ws.rs.core.MediaType;
 import org.keycloak.representations.idm.ClientTypesRepresentation;
 
 /**
+ *  @since Keycloak 25. All the child endpoints are also available since that version<p>
+ *
+ *  This endpoint including all the child endpoints requires feature {@link org.keycloak.common.Profile.Feature#CLIENT_TYPES} to be enabled<p>
+ *
  * @author <a href="mailto:mposolda@redhat.com">Marek Posolda</a>
  */
 public interface ClientTypesResource {

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/GroupResource.java

@@ -104,9 +104,9 @@ public interface GroupResource {
      * Get the paginated list of subgroups belonging to this group, filtered according to the specified parameters.
      *
      * @param search a {@code String} representing either an exact group name or a partial name. If empty or {@code null}
-     *              then all subgroups of this group are returned.
+     *              then all subgroups of this group are returned. Parameter available since Keycloak server 25. Will be ignored on older Keycloak versions with the default value null.
      * @param exact if {@code true}, the subgroups will be searched using exact match for the {@code search} param. If false
-     *              or {@code null}, the method returns all subgroups that partially match the specified name.
+     *              or {@code null}, the method returns all subgroups that partially match the specified name. Parameter available since Keycloak server 25. Will be ignored on older Keycloak versions with the default value null.
      * @param first the position of the first result to be returned.
      * @param max the maximum number of results that are to be returned.
      * @param briefRepresentation if {@code true}, each returned subgroup representation will only contain basic information

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/IdentityProvidersResource.java

@@ -50,6 +50,18 @@ public interface IdentityProvidersResource {
     List<IdentityProviderRepresentation> find(@QueryParam("search") String search, @QueryParam("briefRepresentation") Boolean briefRepresentation,
                                               @QueryParam("first") Integer firstResult, @QueryParam("max") Integer maxResults);
 
+    /**
+     * Get the paginated list of identity providers, filtered according to the specified parameters.
+     *
+     * @param search Filter to search specific providers by name. Search can be prefixed (name*), contains (*name*) or exact (\"name\"). Default prefixed.
+     * @param briefRepresentation Boolean which defines whether brief representations are returned (default: false).
+     *                            If true, only basic data like ID, alias, providerId and enabled status will be returned in the result
+     * @param firstResult Pagination offset
+     * @param maxResults Maximum results size (defaults to 100)
+     * @param realmOnly Boolean which defines if only realm-level IDPs (not associated with orgs) should be returned (default: false).
+     *                  Parameter available since Keycloak server 26. Will be ignored on older Keycloak versions with the default value false
+     * @return The list of providers.
+     */
     @GET
     @Path("instances")
     @Produces(MediaType.APPLICATION_JSON)

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/OrganizationMemberResource.java

@@ -37,6 +37,12 @@ public interface OrganizationMemberResource {
     @DELETE
     Response delete();
 
+    /**
+     * Returns the organizations associated with the user
+     *
+     * @since Keycloak server 26
+     * @return the organizations associated with the user
+     */
     @Path("organizations")
     @GET
     @Produces(MediaType.APPLICATION_JSON)

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/OrganizationMembersResource.java

@@ -82,6 +82,10 @@ public interface OrganizationMembersResource {
     @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
     Response inviteExistingUser(@FormParam("id") String id);
 
+    /**
+     * @since Keycloak server 26
+     * @return count of members of the organization
+     */
     @Path("count")
     @GET
     @Produces(MediaType.APPLICATION_JSON)

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/OrganizationsResource.java

@@ -30,6 +30,11 @@ import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 import org.keycloak.representations.idm.OrganizationRepresentation;
 
+/**
+ * @since Keycloak 25. All the child endpoints are also available since that version<p>
+ *
+ * This endpoint including all the child endpoints requires feature {@link org.keycloak.common.Profile.Feature#ORGANIZATION} to be enabled<p>
+ */
 public interface OrganizationsResource {
 
     @POST

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/RealmResource.java

@@ -267,6 +267,13 @@ public interface RealmResource {
     @Produces(MediaType.APPLICATION_JSON)
     GlobalRequestResult logoutAll();
 
+    /**
+     * Delete given user session
+     *
+     * @param sessionId session ID
+     * @param offline Parameter available since Keycloak server 24.0.2. Will be ignored on older Keycloak versions with the default value false.
+     * @throws jakarta.ws.rs.NotFoundException if the user session is not found
+     */
     @Path("sessions/{session}")
     @DELETE
     void deleteSession(@PathParam("session") String sessionId, @DefaultValue("false") @QueryParam("isOffline") boolean offline);

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/RoleResource.java

@@ -110,7 +110,7 @@ public interface RoleResource {
      * Note: This method just returns the first 100 users. In order to retrieve all users, use paging (see
      * {@link #getUserMembers(Integer, Integer)}).
      * </p>
-     * 
+     *
      * @return a list of users with the given role
      */
     @GET
@@ -138,7 +138,7 @@ public interface RoleResource {
      * <p>Returns users that have the given role, sorted by username ascending, paginated according to the query
      * parameters.</p>
      *
-     * @param briefRepresentation If the user should be returned in brief or full representation
+     * @param briefRepresentation If the user should be returned in brief or full representation. Parameter available since Keycloak server 26. Will be ignored on older Keycloak versions with the default value false.
      * @param firstResult Pagination offset
      * @param maxResults Pagination size
      * @return a list of users with the given role
@@ -149,7 +149,7 @@ public interface RoleResource {
     List<UserRepresentation> getUserMembers(@QueryParam("briefRepresentation") Boolean briefRepresentation,
             @QueryParam("first") Integer firstResult,
             @QueryParam("max") Integer maxResults);
-    
+
     /**
      * Get role groups.
      * <p>Returns groups that have the given role.</p>

integration/admin-client/src/main/java/org/keycloak/admin/client/resource/UserResource.java

@@ -71,7 +71,7 @@ public interface UserResource {
     List<GroupRepresentation> groups(@QueryParam("search") String search,
                                      @QueryParam("first") Integer firstResult,
                                      @QueryParam("max") Integer maxResults);
-    
+
     @Path("groups")
     @GET
     List<GroupRepresentation> groups(@QueryParam("first") Integer firstResult,
@@ -330,6 +330,10 @@ public interface UserResource {
     @Produces(MediaType.APPLICATION_JSON)
     Map<String, Object> impersonate();
 
+    /**
+     * @since Keycloak server 24.0.6
+     * @return unmanaged attributes of the user
+     */
     @GET
     @Path("unmanagedAttributes")
     @Produces(MediaType.APPLICATION_JSON)