Improve javadoc for admin-client methods with injecting own resteasyClient

closes #40231

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

integration/admin-client/src/main/java/org/keycloak/admin/client/Keycloak.java

@@ -101,39 +101,80 @@ public class Keycloak implements AutoCloseable {
     private BearerAuthFilter newAuthFilter() {
         return authToken != null ? new BearerAuthFilter(authToken) : new BearerAuthFilter(tokenManager);
     }
-    
+
+    /**
+     *
+     * Creates the java admin client instance to be used to call admin REST API against Keycloak server.
+     *
+     * @param serverUrl Keycloak server URL
+     * @param realm realm name
+     * @param username username of the admin user to be used.
+     * @param password password of the admin user
+     * @param clientId client ID
+     * @param clientSecret client secret. Could be left null in case that clientId parameter points to the public client, which does not require client authentication
+     * @param sslContext ssl context. Could be left null in case that default SSL context should be used.
+     * @param customJacksonProvider custom Jackson provider. Could be left null in case that Jackson provider will be automatically provided by the admin client. Please see <a href="https://www.keycloak.org/securing-apps/admin-client#_admin_client_compatibility">the documentation</a> for additional details regarding the compatibility
+     * @param disableTrustManager If to disable trust manager for SSL checks. It is false by default. The value true should be used just for the development purposes, but should not be used in production
+     * @param authToken access token to be used to call admin REST API. This can be left null if you want admin client to login the user (based on the parameters username, password, clientId and clientSecret) and manage it's own login session. But in case you already have existing session, you can inject the existing access token with the use of this parameter. In that case, it is recommended to leave the properties username, password, clientId or clientSecret empty
+     * @param scope Custom "scope" parameter to be used. Could be left null in case of default scope should be used. That is sufficient for most of the cases.
+     * @return Java admin client instance
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, String clientSecret, SSLContext sslContext, Object customJacksonProvider, boolean disableTrustManager, String authToken, String scope) {
         return new Keycloak(serverUrl, realm, username, password, clientId, clientSecret, PASSWORD, newRestEasyClient(customJacksonProvider, sslContext, disableTrustManager), authToken, scope);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, String clientSecret, SSLContext sslContext, Object customJacksonProvider, boolean disableTrustManager, String authToken) {
         return new Keycloak(serverUrl, realm, username, password, clientId, clientSecret, PASSWORD, newRestEasyClient(customJacksonProvider, sslContext, disableTrustManager), authToken, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, String clientSecret) {
         return getInstance(serverUrl, realm, username, password, clientId, clientSecret, null, null, false, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, String clientSecret, SSLContext sslContext) {
         return getInstance(serverUrl, realm, username, password, clientId, clientSecret, sslContext, null, false, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, String clientSecret, SSLContext sslContext, Object customJacksonProvider) {
         return getInstance(serverUrl, realm, username, password, clientId, clientSecret, sslContext, customJacksonProvider, false, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId) {
         return getInstance(serverUrl, realm, username, password, clientId, null, null, null, false, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String username, String password, String clientId, SSLContext sslContext) {
         return getInstance(serverUrl, realm, username, password, clientId, null, sslContext, null, false, null);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String clientId, String authToken) {
         return getInstance(serverUrl, realm, null, null, clientId, null, null, null, false, authToken);
     }
 
+    /**
+     * See {@link #getInstance(String, String, String, String, String, String, SSLContext, Object, boolean, String, String)} for the details about the parameters and their default values
+     */
     public static Keycloak getInstance(String serverUrl, String realm, String clientId, String authToken, SSLContext sllSslContext) {
         return getInstance(serverUrl, realm, null, null, clientId, null, sllSslContext, null, false, authToken);
     }

integration/admin-client/src/main/java/org/keycloak/admin/client/KeycloakBuilder.java

@@ -35,7 +35,10 @@ import jakarta.ws.rs.client.Client;
  *     .password("pass")
  *     .clientId("client")
  *     .clientSecret("secret")
- *     .resteasyClient(new ResteasyClientBuilder().connectionPoolSize(20).build())
+ *     .resteasyClient(new ResteasyClientBuilderImpl()
+ *                 .connectionPoolSize(20)
+ *                 .build()
+ *                 .register(org.keycloak.admin.client.JacksonProvider.class, 100))
  *     .build();
  * </pre>
  * <p>Example usage with grant_type=client_credentials</p>
@@ -105,6 +108,12 @@ public class KeycloakBuilder {
         return this;
     }
 
+    /**
+     * Custom instance of resteasy client. Please see <a href="https://www.keycloak.org/securing-apps/admin-client#_admin_client_compatibility">the documentation</a> for additional details regarding the compatibility
+     *
+     * @param resteasyClient Custom RestEasy client
+     * @return admin client builder
+     */
     public KeycloakBuilder resteasyClient(Client resteasyClient) {
         this.resteasyClient = resteasyClient;
         return this;