8000 Add `@DefaultValue` to document the max param used in several Admin REST APIs by IestynGage · Pull Request #47561 · keycloak/keycloak · GitHub
[go: up one dir, main page]
Skip to content

Add @DefaultValue to document the max param used in several Admin REST APIs #47561

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
shawkins merged 1 commit into from
May 1, 2026
Merged

Add @DefaultValue to document the max param used in several Admin REST APIs #47561

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions server-spi-private/src/main/java/org/keycloak/models/Constants.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,10 @@ public final class Constants {
public static final String GENERATE = "GENERATE";

public static final int DEFAULT_MAX_RESULTS = 100;
/**
* Used by {@code DefaultValue} annotation for when a REST endpoints max size default is set by {@link #DEFAULT_MAX_RESULTS}.
*/
public static final String DEFAULT_MAX_RESULTS_STR = "" + DEFAULT_MAX_RESULTS;
@vmuzikar vmuzikar Apr 30, 2026
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would be cleaner but it's not blocking, just a nitpick.

Suggested change
public static final String DEFAULT_MAX_RESULTS_STR = "" + DEFAULT_MAX_RESULTS;
public static final String DEFAULT_MAX_RESULTS_STR = String.valueOf(DEFAULT_MAX_RESULTS);

@IestynGage IestynGage May 1, 2026
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but unfortunately, Java doesn't 🤷

When compiling, a element value must be a constant expression is thrown.


// Delimiter to be used in the configuration of authenticators (and some other components) in case that we need to save
// multiple values into single string
Expand Down
3 changes: 2 additions & 1 deletion services/src/main/java/org/keycloak/authorization/admin/PolicyService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@

import jakarta.ws.rs.BadRequestException;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
Expand Down Expand Up @@ -216,7 +217,7 @@ public Response findAll(@QueryParam("policyId") String id,
@QueryParam("owner") String owner,
@QueryParam("fields") String fields,
@QueryParam("first") Integer firstResult,
@QueryParam("max") Integer maxResult) {
@QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResult) {
if (auth != null) {
this.auth.realm().requireViewAuthorization(resourceServer);
}
Expand Down
5 changes: 3 additions & 2 deletions services/src/main/java/org/keycloak/authorization/admin/ResourceSetService.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.POST;
Expand Down Expand Up @@ -402,7 +403,7 @@ public Response find(@QueryParam("_id") String id,
@QueryParam("exactName") Boolean exactName,
@QueryParam("deep") Boolean deep,
@QueryParam("first") Integer firstResult,
@QueryParam("max") Integer maxResult) {
@QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResult) {
return find(id, name, uri, owner, type, scope, matchingUri, exactName, deep, firstResult, maxResult, (BiFunction<Resource, Boolean, ResourceRepresentation>) (resource, deep1) -> toRepresentation(resource, resourceServer, authorization, deep1));
}

Expand All @@ -416,7 +417,7 @@ public Response find(@QueryParam("_id") String id,
@QueryParam("exactName") Boolean exactName,
@QueryParam("deep") Boolean deep,
@QueryParam("first") Integer firstResult,
@QueryParam("max") Integer maxResult,
@QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResult,
BiFunction<Resource, Boolean, ?> toRepresentation) {
requireView();

Expand Down
9 changes: 5 additions & 4 deletions services/src/main/java/org/keycloak/services/resources/admin/ClientResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
import jakarta.ws.rs.BadRequestException;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.DELETE;
import jakarta.ws.rs.DefaultValue;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.NotFoundException;
import jakarta.ws.rs.POST;
Expand Down Expand Up @@ -569,8 +570,8 @@ public Map<String, Long> getApplicationSessionCount() {
@NoCache
@Produces(MediaType.APPLICATION_JSON)
@Tag(name = KeycloakOpenAPI.Admin.Tags.CLIENTS)
@Operation( summary = "Get user sessions for client Returns a list of user sessions associated with this client\n")
public Stream<UserSessionRepresentation> getUserSessions(@Parameter(description = "Paging offset") @QueryParam("first") Integer firstResult, @Parameter(description = "Maximum results size (defaults to 100)") @QueryParam("max") Integer maxResults) {
@Operation( summary = "Get user sessions for client. Returns a list of user sessions associated with this client.\n")
public Stream<UserSessionRepresentation> getUserSessions(@Parameter(description = "Paging offset") @QueryParam("first") Integer firstResult, @Parameter(description = "Maximum results size.") @QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResults) {
auth.clients().requireView(client);
return session.sessions()
.readOnlyStreamUserSessions(client.getRealm(), client, computeFirstResult(firstResult), computeMaxResults(maxResults))
Expand Down Expand Up @@ -616,8 +617,8 @@ public Map<String, Long> getOfflineSessionCount() {
@NoCache
@Produces(MediaType.APPLICATION_JSON)
@Tag(name = KeycloakOpenAPI.Admin.Tags.CLIENTS)
@Operation( summary = "Get offline sessions for client Returns a list of offline user sessions associated with this client")
public Stream<UserSessionRepresentation> getOfflineUserSessions(@Parameter(description = "Paging offset") @QueryParam("first") Integer firstResult, @Parameter(description = "Maximum results size (defaults to 100)") @QueryParam("max") Integer maxResults) {
@Operation( summary = "Get offline sessions for client. Returns a list of offline user sessions associated with this client")
public Stream<UserSessionRepresentation> getOfflineUserSessions(@Parameter(description = "Paging offset") @QueryParam("first") Integer firstResult, @Parameter(description = "Maximum results size.") @QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResults) {
auth.clients().requireView(client);
return session.sessions()
.readOnlyStreamOfflineUserSessions(client.getRealm(), client, computeFirstResult(firstResult), computeMaxResults(maxResults))
Expand Down
2 changes: 1 addition & 1 deletion services/src/main/java/org/keycloak/services/resources/admin/RealmAdminResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -902,7 +902,7 @@ public Stream<EventRepresentation> getEvents(@Parameter(description = "The types
@Parameter(description = "To (inclusive) date (yyyy-MM-dd) or time in Epoch timestamp millis (number of milliseconds since January 1, 1970, 00:00:00 GMT)") @QueryParam("dateTo") String dateTo,
@Parameter(description = "IP Address") @QueryParam("ipAddress") String ipAddress,
@Parameter(description = "Paging offset") @QueryParam("first") Integer firstResult,
@Parameter(description = "Maximum results size (defaults to 100)") @QueryParam("max") Integer maxResults,
@Parameter(description = "Maximum results size") @QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResults,
@Parameter(description = "The direction to sort events by (asc or desc)") @QueryParam("direction") String direction) {
auth.realm().requireViewEvents();

Expand Down
12 changes: 6 additions & 6 deletions services/src/main/java/org/keycloak/services/resources/admin/RoleContainerResource.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -563,7 +563,7 @@ public ManagementPermissionReference setManagementPermissionsEnabled(final @Path
*
* @param roleName the role name.
* @param firstResult first result to return. Ignored if negative or {@code null}.
* @param maxResults maximum number of results to return. Ignored if negative or {@code null}.
* @param maxResults maximum number of results to return. Unbounded if negative.
* @param briefRepresentation Boolean which defines whether brief representations are returned (default: false)
* @return a non-empty {@code Stream} of users.
*/
Expand All @@ -581,7 +581,7 @@ public ManagementPermissionReference setManagementPermissionsEnabled(final @Path
public Stream<UserRepresentation> getUsersInRole(final @Parameter(description = "the role name.") @PathParam("role-name") String roleName,
@Parameter(description = "Boolean which defines whether brief representations are returned (default: false)") @QueryParam("briefRepresentation") Boolean briefRepresentation,
@Parameter(description = "first result to return. Ignored if negative or {@code null}.") @QueryParam("first") Integer firstResult,
@Parameter(description = "maximum number of results to return. Ignored if negative or {@code null}.") @QueryParam("max") Integer maxResults) {
@Parameter(description = "Maximum number of results to return. Unbounded if negative.") @QueryParam("max") @DefaultValue(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResults) {
Comment thread
vmuzikar marked this conversation as resolved.
Resolved

auth.roles().requireView(roleContainer);
auth.users().requireQuery();
Expand All @@ -607,7 +607,7 @@ public Stream<UserRepresentation> getUsersInRole(final @Parameter(description =
*
* @param roleName the role name.
* @param firstResult first result to return. Ignored if negative or {@code null}.
* @param maxResults maximum number of results to return. Ignored if negative or {@code null}.
* @param maxResults maximum number of results to return. Unbounded if negative.
* @param briefRepresentation if false, return a full representation of the {@code GroupRepresentation} objects.
* @return a non-empty {@code Stream} of groups.
*/
Expand All @@ -623,9 +623,9 @@ public Stream<UserRepresentation> getUsersInRole(final @Parameter(description =
@APIResponse(responseCode = "404", description = "Not Found")
})
public Stream<GroupRepresentation> getGroupsInRole(final @Parameter(description = "the role name.") @PathParam("role-name") String roleName,
@Parameter(description = "first result to return. Ignored if negative or {@code null}.") @QueryParam("first") Integer firstResult,
@Parameter(description = "maximum number of results to return. Ignored if negative or {@code null}.") @QueryParam("max") Integer maxResults,
@Parameter(description = "if false, return a full representation of the {@code GroupRepresentation} objects.") @QueryParam("briefRepresentation") @DefaultValue("true") boolean briefRepresentation) {
@Parameter(description = "First result to return. Ignored if negative or {@code null}.") @QueryParam("first") Integer firstResult,
@Parameter(description = "Maximum number of results to return. Unbounded if negative.") @QueryParam(Constants.DEFAULT_MAX_RESULTS_STR) Integer maxResults,
@Parameter(description = "If false, return a full representation of the {@code GroupRepresentation} objects.") @QueryParam("briefRepresentation") @DefaultValue("true") boolean briefRepresentation) {

auth.roles().requireView(roleContainer);
firstResult = firstResult != null ? firstResult : 0;
Expand Down
Loading
0