Review API docs in BI editor

ballerina/client_oauth2_provider.bal

@@ -20,17 +20,17 @@ import ballerina/url;
 
 const UTF8 = "UTF-8";
 
-# Represents the data structure, which is used to configure the OAuth2 client credentials grant type.
+# The configurations for the OAuth2 client credentials grant type.
 #
-# + tokenUrl - Token URL of the token endpoint
-# + clientId - Client ID of the client authentication
-# + clientSecret - Client secret of the client authentication
-# + scopes - Scope(s) of the access request
-# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field
-# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
-# + optionalParams - Map of the optional parameters used for the token endpoint
-# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint
-# + clientConfig - HTTP client configurations, which are used to call the token endpoint
+# + tokenUrl - The URL of the token endpoint
+# + clientId - The client ID of the client authentication
+# + clientSecret - The client secret of the client authentication
+# + scopes - The scope(s) of the access request. This can be a single string or an array of strings
+# + defaultTokenExpTime -  The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field
+# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues
+# + optionalParams - A map of optional parameters to be sent to the token endpoint
+# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint
+# + clientConfig - HTTP client configurations used to make requests to the token endpoint
 public type ClientCredentialsGrantConfig record {|
     string tokenUrl;
     string clientId;
@@ -46,13 +46,13 @@ public type ClientCredentialsGrantConfig record {|
 # Constant used to infer the values of refreshConfig from values provided for PasswordGrantConfig.
 public const INFER_REFRESH_CONFIG = "INFER_REFRESH_CONFIG";
 
-# Represents the data structure, which is used for refresh configuration of the OAuth2 password grant type.
+# The refresh configurations for the OAuth2 password grant type.
 #
-# + refreshUrl - Refresh token URL of the token endpoint
-# + scopes - Scope(s) of the referesh token request
-# + optionalParams - Map of the optional parameters used for the token endpoint
-# + credentialBearer - Bearer of the authentication credential, which is sent to the token endpoint
-# + clientConfig - HTTP client configuration, which is used to call the refresh token endpoint
+# + refreshUrl - The URL of the refresh token endpoint
+# + scopes - The scope(s) of the refresh token request. This can be a single string or an array of strings
+# + optionalParams - A map of optional parameters to be sent to the refresh token endpoint
+# + credentialBearer - The bearer type for authentication credentials sent to the refresh token endpoint
+# + clientConfig - HTTP client configurations used to make requests to the refresh token endpoint
 public type RefreshConfig record {|
     string refreshUrl;
     string|string[] scopes?;
@@ -61,20 +61,20 @@ public type RefreshConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-# Represents the data structure, which is used to configure the OAuth2 password grant type.
+# The configurations for the OAuth2 password grant type.
 #
-# + tokenUrl - Token URL of the token endpoint
-# + username - Username for the password grant type
-# + password - Password for the password grant type
-# + clientId - Client ID of the client authentication
-# + clientSecret - Client secret of the client authentication
-# + scopes - Scope(s) of the access request
-# + refreshConfig - Configurations for refreshing the access token
-# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field
-# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
-# + optionalParams - Map of the optional parameters used for the token endpoint
-# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint
-# + clientConfig - HTTP client configurations, which are used to call the token endpoint
+# + tokenUrl - The URL of the token endpoint
+# + username - The username for the password grant type
+# + password - The password for the password grant type
+# + clientId - The client ID for client authentication
+# + clientSecret - The client secret for client authentication
+# + scopes - The scope(s) of the access request. This can be a single string or an array of strings
+# + refreshConfig - The configurations for refreshing the access token. Can be a `RefreshConfig` or `oauth2:INFER_REFRESH_CONFIG`
+# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field
+# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues
+# + optionalParams - A map of optional parameters to be sent to the token endpoint
+# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint
+# + clientConfig - HTTP client configurations used to make requests to the token endpoint
 public type PasswordGrantConfig record {|
     string tokenUrl;
     string username;
@@ -90,18 +90,18 @@ public type PasswordGrantConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-# Represents the data structure, which is used to configure the OAuth2 refresh token grant type.
+# The configurations for the OAuth2 refresh token grant type.
 #
-# + refreshUrl - Refresh token URL of the token endpoint
-# + refreshToken - Refresh token for the token endpoint
-# + clientId - Client ID of the client authentication
-# + clientSecret - Client secret of the client authentication
-# + scopes - Scope(s) of the access request
-# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field
-# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
-# + optionalParams - Map of the optional parameters used for the token endpoint
-# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint
-# + clientConfig - HTTP client configurations, which are used to call the token endpoint
+# + refreshUrl - The URL of the refresh token endpoint
+# + refreshToken - The refresh token used to obtain a new access token
+# + clientId - The client ID for client authentication
+# + clientSecret - The client secret for client authentication
+# + scopes - The scope(s) of the access request. This can be a single string or an array of strings
+# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field
+# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues
+# + optionalParams - A map of optional parameters to be sent to the token endpoint
+# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint
+# + clientConfig - HTTP client configurations used to make requests to the token endpoint
 public type RefreshTokenGrantConfig record {|
     string refreshUrl;
     string refreshToken;
@@ -115,18 +115,18 @@ public type RefreshTokenGrantConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-# Represents the data structure, which is used to configure the OAuth2 JWT bearer grant type.
+# The configurations for the OAuth2 JWT bearer grant type.
 #
-# + tokenUrl - Token URL of the token endpoint
-# + assertion - A single JWT for the JWT bearer grant type
-# + clientId - Client ID of the client authentication
-# + clientSecret - Client secret of the client authentication
-# + scopes - Scope(s) of the access request
-# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the token endpoint response does not contain an `expires_in` field
-# + clockSkew - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
-# + optionalParams - Map of the optional parameters used for the token endpoint
-# + credentialBearer - Bearer of the authentication credentials, which is sent to the token endpoint
-# + clientConfig - HTTP client configurations, which are used to call the token endpoint
+# + tokenUrl - The URL of the token endpoint
+# + assertion - A single JWT used for the JWT bearer grant type
+# + clientId - The client ID for client authentication
+# + clientSecret - The client secret for client authentication
+# + scopes - The scope(s) of the access request. This can be a single string or an array of strings
+# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the token endpoint response does not include an `expires_in` field
+# + clockSkew - The clock skew (in seconds) to account for clock synchronization issues
+# + optionalParams - A map of optional parameters to be sent to the token endpoint
+# + credentialBearer - The bearer type for authentication credentials sent to the token endpoint
+# + clientConfig - HTTP client configurations used to make requests to the token endpoint
 public type JwtBearerGrantConfig record {|
     string tokenUrl;
     string assertion;
@@ -140,7 +140,7 @@ public type JwtBearerGrantConfig record {|
     ClientConfiguration clientConfig = {};
 |};
 
-// The data structure, which stores the values needed to prepare the HTTP request, which are to be sent to the
+// Represents the values needed to prepare the HTTP request, which are to be sent to the
 // token endpoint.
 type RequestConfig record {|
     string payload;
@@ -151,10 +151,10 @@ type RequestConfig record {|
     CredentialBearer credentialBearer;
 |};
 
-# Represents the grant type configurations supported for OAuth2.
+# The grant type configurations supported for OAuth2.
 public type GrantConfig ClientCredentialsGrantConfig|PasswordGrantConfig|RefreshTokenGrantConfig|JwtBearerGrantConfig;
 
-# Represents the client OAuth2 provider, which is used to generate OAuth2 access tokens using the configured OAuth2
+# The client OAuth2 provider, which is used to generate OAuth2 access tokens using the configured OAuth2
 # token endpoint configurations. This supports the client credentials grant type, password grant type,
 # refresh token grant type, and the JWT bearer grant type.
 #
@@ -197,7 +197,11 @@ public isolated class ClientOAuth2Provider {
 
     # Provides authorization based on the provided OAuth2 configurations.
     #
-    # + grantConfig - OAuth2 grant type configurations
+    # + grantConfig - The OAuth2 grant type configurations. This can be one of the following:
+    #   - `ClientCredentialsGrantConfig`: Configuration for the client credentials grant type.
+    #   - `PasswordGrantConfig`: Configuration for the password grant type.
+    #   - `RefreshTokenGrantConfig`: Configuration for the refresh token grant type.
+    #   - `JwtBearerGrantConfig`: Configuration for the JWT bearer grant type.
     public isolated function init(GrantConfig grantConfig) {
         self.grantConfig = grantConfig.cloneReadOnly();
         self.tokenCache = new;
@@ -208,12 +212,12 @@ public isolated class ClientOAuth2Provider {
         }
     }
 
-    # Get an OAuth2 access token from the token endpoint.
+    # Gets an OAuth2 access token from the token endpoint.
     # ```ballerina
     # string token = check provider.generateToken();
     # ```
     #
-    # + return - Received OAuth2 access token or else an `oauth2:Error` if an error occurred
+    # + return - The received OAuth2 access token as a `string` or an `oauth2:Error` if an error occurred
     public isolated function generateToken() returns string|Error {
         string|Error authToken = generateOAuth2Token(self.grantConfig, self.tokenCache);
         if authToken is string {

ballerina/listener_oauth2_provider.bal

@@ -18,14 +18,14 @@ import ballerina/cache;
 import ballerina/log;
 import ballerina/time;
 
-# Represents the introspection endpoint configurations.
+# The configurations for the introspection endpoint.
 #
-# + url - URL of the introspection endpoint
+# + url - The URL of the introspection endpoint
 # + tokenTypeHint - A hint about the type of the token submitted for introspection
-# + optionalParams - Map of the optional parameters used for the introspection endpoint
-# + cacheConfig - Configurations for the cache used to store the OAuth2 access token and other related information
-# + defaultTokenExpTime - Expiration time (in seconds) of the tokens if the introspection response does not contain an `exp` field
-# + clientConfig - HTTP client configurations, which call the introspection endpoint
+# + optionalParams - A map of the optional parameters used for the introspection endpoint
+# + cacheConfig - The configurations for the cache used to store the OAuth2 access token and other related information
+# + defaultTokenExpTime - The default expiration time (in seconds) for tokens if the introspection response does not include an `exp` field
+# + clientConfig - The HTTP client configurations used to call the introspection endpoint
 public type IntrospectionConfig record {
     string url;
     string tokenTypeHint?;
@@ -35,20 +35,20 @@ public type IntrospectionConfig record {
     ClientConfiguration clientConfig = {};
 };
 
-# Represents the introspection endpoint response.
+# The introspection endpoint response type.
 #
-# + active - Boolean indicator of whether or not the presented token is currently active
+# + active - A boolean indicating whether the presented token is currently active
 # + scope - A JSON string containing a space-separated list of scopes associated with this token
-# + clientId - Client identifier for the OAuth 2.0 client, which requested this token
-# + username - Resource owner who authorized this token
-# + tokenType - Type of the token
-# + exp - Expiry time (seconds since the Epoch)
-# + iat - Time when the token was issued originally (seconds since the Epoch)
-# + nbf - Token is not to be used before this time (seconds since the Epoch)
-# + sub - Subject of the token
-# + aud - Intended audience of the token
-# + iss - Issuer of the token
-# + jti - String identifier for the token
+# + clientId - The client identifier for the OAuth 2.0 client that requested this token
+# + username - The resource owner who authorized this token
+# + tokenType - The type of the token
+# + exp - The expiration time of the token (in seconds since the Epoch)
+# + iat - The time when the token was issued (in seconds since the Epoch)
+# + nbf - The time before which the token must not be used (in seconds since the Epoch)
+# + sub - The subject of the token
+# + aud - The intended audience of the token
+# + iss - The issuer of the token
+# + jti - A unique identifier for the token
 public type IntrospectionResponse record {
     boolean active;
     string scope?;
@@ -78,7 +78,7 @@ const string AUD = "aud";
 const string ISS = "iss";
 const string JTI = "jti";
 
-# Represents the listener OAuth2 provider, which is used to validate the received credential (access token) by
+# The listener for the OAuth2 provider, which is used to validate the received credential (access token) by
 # calling the configured introspection endpoint.
 # ```ballerina
 # oauth2:IntrospectionConfig config = {
@@ -111,13 +111,13 @@ public isolated class ListenerOAuth2Provider {
         }
     }
 
-    # Validates the provided OAuth2 acess token against the introspection endpoint.
+    # Validates the provided OAuth2 access token against the introspection endpoint.
     # ```ballerina
     # boolean result = check provider.authorize("<credential>");
     # ```
     #
-    # + credential - OAuth2 access token to be validated
-    # + optionalParams - Map of the optional parameters used for the introspection endpoint
+    # + credential - The OAuth2 access token to be validated
+    # + optionalParams - A map of optional parameters to be sent to the introspection endpoint
     # + return - An `oauth2:IntrospectionResponse` if the validation is successful or else an `oauth2:Error` if an error occurred
     public isolated function authorize(string credential, map<string>? optionalParams = ()) returns IntrospectionResponse|Error {
         if credential == "" {

ballerina/oauth2_commons.bal

@@ -17,11 +17,11 @@
 import ballerina/crypto;
 import ballerina/jballerina.java;
 
-# Represents the configurations of the client used to call the introspection endpoint.
+# The configurations of the client used to call the introspection endpoint.
 #
 # + httpVersion - The HTTP version of the client
-# + customHeaders - The list of custom HTTP headers
-# + customPayload - The list of custom HTTP payload parameters
+# + customHeaders - A map of custom HTTP headers to be included in the request
+# + customPayload - A custom HTTP payload to be sent with the request
 # + auth - The client auth configurations
 # + secureSocket - SSL/TLS-related configurations
 # + connectTimeout - Maximum time(in seconds) to wait for a connection to be established. By default, uses the global
@@ -38,16 +38,16 @@ public type ClientConfiguration record {|
     decimal reqTimeout?;
 |};
 
-# Represents the the authentication configuration types for the HTTP client used for token introspection.
+# The authentication configuration types for the HTTP client used for token introspection.
 public type ClientAuth ClientCredentialsGrantConfig|PasswordGrantConfig|RefreshTokenGrantConfig;
 
-# Represents the HTTP versions.
+# The HTTP versions.
 public enum HttpVersion {
     HTTP_1_1,
     HTTP_2
 }
 
-# Represents the SSL/TLS configurations.
+# The SSL/TLS configurations.
 #
 # + disable - Disable SSL validation
 # + cert - Configurations associated with the `crypto:TrustStore` or single certificate file that the client trusts
@@ -58,7 +58,7 @@ public type SecureSocket record {|
     crypto:KeyStore|CertKey key?;
 |};
 
-# Represents the combination of the certificate file path, private key file path, and private key password if encrypted.
+# The combination of the certificate file path, private key file path, and private key password if encrypted.
 #
 # + certFile - A file containing the certificate
 # + keyFile - A file containing the private key
@@ -69,7 +69,7 @@ public type CertKey record {|
    string keyPassword?;
 |};
 
-# Represents the credential-bearing methods.
+# The credential-bearing methods.
 public enum CredentialBearer {
     AUTH_HEADER_BEARER,
     POST_BODY_BEARER

ballerina/oauth2_errors.bal

@@ -16,7 +16,7 @@
 
 import ballerina/log;
 
-# Represents the error type of the module. This will be returned if an error occurred while the listener OAuth2 provider
+# The error type of the module. This will be returned if an error occurred while the listener OAuth2 provider
 # tries to validate the received credentials and the client OAuth2 provider tries to generate the token.
 public type Error distinct error;