docs: Fix all docs from one <p> represents for a paragraph

2023-07-31 21:43:09 +08:00
parent 373fbf9083
commit 715ae6db3a
28 changed files with 627 additions and 133 deletions
@@ -19,6 +19,6 @@
 * Commonly used exceptions will be used in JDevKit.
 *
 * @author Zihlu Wang
- * @since 29 Jul 2023
+ * @since 1.0.0
 */
 package cn.org.codecrafters.devkit.core.exceptions;
@@ -16,16 +16,20 @@
 */

 /**
+ * <p>
 * This package is a part of JDevKit, an open-source Java Development Kit that
 * provides a set of convenient tools to streamline code development and
 * enhance productivity. This package serves as the core package containing
 * common exceptions that are used throughout the entireJDevKit project.
+ * </p>
 * <p>
 * JDevKit is designed to be modular, and other specific feature modules within
 * the library may rely on these exceptions from the core package.
+ * </p>
 * <p>
 * For more information and the latest version of JDevKit, please visit our
 * website <a href="https://codecrafters.org.cn">codecrafters.org.cn</a>.
+ * </p>
 * <p>
 * <h4>Contact</h4>
 * <ul>
@@ -37,6 +41,7 @@
 *         <a href="https://discord.gg/">Discord Community</a>
 *     </li>
 * </ul>
+ * </p>
 *
 * @since 1.0.0
 */
@@ -22,9 +22,11 @@
 * that provides a set of convenient tools to streamline code development and
 * enhance productivity. This package serves as the root package for several
 * modules, containing devkit-core, guid and dev-utils module.
+ * </p>
 * <p>
 * For more information and the latest version of JDevKit, please visit our
 * website <a href="https://codecrafters.org.cn">codecrafters.org.cn</a>.
+ * </p>
 * <p>
 * <h4>Contact</h4>
 * <ul>
@@ -36,5 +38,8 @@
 *         <a href="https://discord.gg/">Discord Community</a>
 *     </li>
 * </ul>
+ * </p>
+ *
+ * @since 1.0.0
 */
 package cn.org.codecrafters.devkit;
@@ -15,13 +15,16 @@
 * limitations under the License.
 */

-package cn.org.codecrafters.devkit.guid;
+package cn.org.codecrafters.guid;

 /**
+ * <p>
 * The {@code GuidCreator} is a generic interface for generating globally unique
 * identifiers (GUIDs) of a specific type.
+ * </p>
 * <p>
 * The type of ID is determined by the class implementing this interface.
+ * </p>
 *
 * @param <IdType> this represents the type of the Global Unique Identifier
 * @author Zihlu Wang
@@ -15,28 +15,30 @@
 * limitations under the License.
 */

-package cn.org.codecrafters.devkit.guid;
+package cn.org.codecrafters.guid;

-import cn.org.codecrafters.devkit.guid.exceptions.TimingException;
+import cn.org.codecrafters.guid.exceptions.TimingException;

 import java.time.LocalDateTime;
 import java.time.ZoneOffset;

 /**
+ * <p>
 * SnowflakeGuidCreator - GUID generator based on the Snowflake algorithm.
- *
+ * </p>
 * <p>
 * The SnowflakeGuidCreator generates unique identifiers using the Snowflake
 * algorithm, which combines a timestamp, worker ID, and data center ID to
 * create 64-bit long integers. The bit distribution for the generated IDs is
 * as follows:
 * <ul>
- * <li>1 bit for sign</li>
- * <li>41 bits for timestamp (in milliseconds)</li>
- * <li>5 bits for data center ID</li>
- * <li>5 bits for worker ID</li>
- * <li>12 bits for sequence number (per millisecond)</li>
+ *     <li>1 bit for sign</li>
+ *     <li>41 bits for timestamp (in milliseconds)</li>
+ *     <li>5 bits for data center ID</li>
+ *     <li>5 bits for worker ID</li>
+ *     <li>12 bits for sequence number (per millisecond)</li>
 * </ul>
+ * </p>
 *
 * <p>
 * When initializing the SnowflakeGuidCreator, you must provide the worker ID
@@ -45,6 +47,7 @@ import java.time.ZoneOffset;
 * increments for IDs generated within the same millisecond. If the system
 * clock moves backward, an exception is thrown to prevent generating IDs with
 * repeated timestamps.
+ * </p>
 *
 * @author Zihlu Wang
 * @version 1.0.0
@@ -15,25 +15,30 @@
 * limitations under the License.
 */

-package cn.org.codecrafters.devkit.guid.exceptions;
+package cn.org.codecrafters.guid.exceptions;

 /**
+ * <p>
 * The TimingException class represents an exception that is thrown when there
 * is an error related to time sequence.
+ * </p>
 * <p>
 * This class extends the RuntimeException class, which means that instances of
 * TimingException do not need to be declared in a method or constructor's
 * throws clause.
+ * </p>
 * <p>
 * Instances of TimingException can be created with or without a message and a
 * cause. The message provides a description of the exception, while the cause
 * represents the underlying cause of the exception and provides additional
 * information about the error.
+ * </p>
 * <p>
 * TimingException is typically used to handle exceptions related to timing,
 * such as timeouts or synchronization issues. It is a subclass of
 * RuntimeException, which means it is an unchecked exception and does not need
 * to be caught or declared.
+ * </p>
 *
 * @author Zihlu Wang
 * @since 1.0.0
@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <p>
+ * This package contains the custom exception classes related to GUID
+ * generation. These exceptions are thrown when there are issues or errors
+ * during the generation or processing of global unique identifiers (GUIDs).
+ * </p>
+ *
+ * <p>
+ * The main exception class in this package is {@link
+ * cn.org.codecrafters.guid.exceptions.TimingException}, which is a runtime
+ * exception and serves as the base exception for all other custom exceptions
+ * related to GUID generation.
+ * </p>
+ *
+ * <p>
+ * Custom exceptions in this package provide specific information about the
+ * type of error that occurred during GUID generation, making it easier for
+ * developers to handle and respond to different scenarios when dealing with
+ * GUIDs. They are designed to enhance the robustness and reliability of the
+ * GUID generation process by providing clear and meaningful error messages to
+ * the developers.
+ * </p>
+ *
+ * <p>
+ * Developers using the GUID generation module should be aware of the possible
+ * exceptions that can be thrown and handle them appropriately to ensure smooth
+ * operation and error handling in their applications.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+package cn.org.codecrafters.guid.exceptions;
@@ -16,12 +16,15 @@
 */

 /**
+ * <p>
 * The package provides a set of tools for generating globally unique
 * identifiers (GUIDs).
+ * </p>
 * <p>
 * The goal of this library is to provide an efficient, reliable way to
 * generate globally unique identifiers without requiring any specific
 * environment or configuration.
+ * </p>
 * <p>
 * Key features include:
 * <ul>
@@ -29,7 +32,8 @@
 *     <li>High performance and quick response</li>
 *     <li>Easy to integrate</li>
 * </ul>
+ * </p>
 *
 * @since 1.0.0
 */
-package cn.org.codecrafters.devkit.guid;
+package cn.org.codecrafters.guid;
@@ -17,7 +17,7 @@

 package cn.org.codecrafters.simplejwt.authzero;

-import cn.org.codecrafters.devkit.guid.GuidCreator;
+import cn.org.codecrafters.guid.GuidCreator;
 import cn.org.codecrafters.simplejwt.TokenPayload;
 import cn.org.codecrafters.simplejwt.TokenResolver;
 import cn.org.codecrafters.simplejwt.annotations.ExcludeFromPayload;
@@ -37,16 +37,19 @@ import java.time.ZoneId;
 import java.util.*;

 /**
+ * <p>
 * The {@code AuthzeroTokenResolver} class is an implementation of the {@link
 * cn.org.codecrafters.simplejwt.TokenResolver} interface. It uses the {@code
 * com.auth0:java-jwt} library to handle JSON Web Token (JWT) resolution. This
 * resolver provides functionality to create, extract, verify, and renew JWT
 * tokens using various algorithms and custom payload data.
+ * </p>
 * <p>
 * <b>Dependencies:</b>
 * This implementation relies on the {@code com.auth0:java-jwt} library. Please
 * ensure you have added this library as a dependency to your project before
 * using this resolver.
+ * </p>
 * <p>
 * <b>Usage:</b>
 * To use the {@code AuthzeroTokenResolver}, first, create an instance of this
@@ -58,6 +61,7 @@ import java.util.*;
 *                               "Token Issuer",
 *                               "Token Secret");
 * }</pre>
+ * </p>
 * <p>
 * Then, you can utilize the various methods provided by this resolver to
 * handle JWT tokens:
@@ -78,12 +82,14 @@ import java.util.*;
 * String renewedToken =
 *     tokenResolver.renew(token, Duration.ofMinutes(30), customPayloads);
 * }</pre>
+ * </p>
 * <p>
 * <b>Note:</b>
 * It is essential to configure the appropriate algorithms, secret, and issuer
 * according to your specific use case when using this resolver.
 * Additionally, ensure that the {@code com.auth0:java-jwt} library is
 * correctly configured in your project's dependencies.
+ * </p>
 *
 * @author Zihlu Wang
 * @version 1.0.0
@@ -232,13 +238,16 @@ public class AuthzeroTokenResolver implements TokenResolver<DecodedJWT> {
    }

    /**
+     * <p>
     * Builds the custom claims of the JSON Web Token (JWT) using the provided
     * Map of claims and adds them to the JWTCreator.Builder.
     * <p>
+     * <p>
     * This method is used to add custom claims to the JWT. It takes a Map of
     * claims, where each entry represents a custom claim name (key) and its
     * corresponding value (value). The custom claims will be added to the JWT
     * using the JWTCreator.Builder.
+     * <p>
     *
     * @param claims  a Map containing the custom claims to be added to the JWT
     * @param builder the JWTCreator.Builder instance to which the custom
@@ -253,9 +262,12 @@ public class AuthzeroTokenResolver implements TokenResolver<DecodedJWT> {
    }

    /**
+     * <p>
     * Finish creating a token.
+     * </p>
     * <p>
     * This is the final step of create a token, to sign this token.
+     * </p>
     *
     * @param builder the builder to build this JWT
     * @return the generated token as a {@code String}
@@ -62,27 +62,35 @@ import java.util.function.Function;
 public final class AuthzeroTokenResolverConfig implements TokenResolverConfig<Function<String, Algorithm>> {

    /**
+     * <p>
     * Constructs a new instance of AuthzeroTokenResolverConfig.
+     * </p>
     * <p>
     * The constructor is set as private to enforce the singleton pattern for
     * this configuration class. Instances of AuthzeroTokenResolverConfig
     * should be obtained through the {@link #getInstance()} method.
+     * </p>
     */
    private AuthzeroTokenResolverConfig() {
    }

    /**
+     * <p>
     * The singleton instance of AuthzeroTokenResolverConfig.
+     * </p>
     * <p>
     * This instance is used to ensure that only one instance of
     * AuthzeroTokenResolverConfig is created and shared throughout the
     * application. The singleton pattern is implemented to provide centralized
     * configuration and avoid redundant object creation.
+     * </p>
     */
    private static AuthzeroTokenResolverConfig instance;

    /**
+     * <p>
     * The supported algorithms and their corresponding algorithm functions.
+     * </p>
     * <p>
     * This map stores the supported algorithms as keys and their corresponding
     * algorithm functions as values. The algorithm functions represent the
@@ -115,14 +123,17 @@ public final class AuthzeroTokenResolverConfig implements TokenResolverConfig<Fu
    }

    /**
+     * <p>
     * Gets the algorithm function corresponding to the specified
     * TokenAlgorithm.
+     * </p>
     * <p>
     * This method returns the algorithm function associated with the given
     * TokenAlgorithm. The provided TokenAlgorithm represents the specific
     * algorithm for which the corresponding algorithm function is required.
     * The returned AlgorithmFunction represents the function implementation
     * that can be used by the TokenResolver to handle the specific algorithm.
+     * </p>
     *
     * @param algorithm the TokenAlgorithm for which the algorithm function is
     *                  required
@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <p>
+ * The package {@code cn.org.codecrafters.simplejwt.authzero.config} contains
+ * configuration classes related to the {@link
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}
+ * implementation.
+ * </p>
+ *
+ * <p>
+ * The classes in this package provide configuration options and settings for
+ * the {@link cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver},
+ * which is used for resolving JSON Web Tokens (JWT) using the Auth0 library.
+ * </p>
+ *
+ * <p>
+ * The {@link
+ * cn.org.codecrafters.simplejwt.authzero.config.AuthzeroTokenResolverConfig}
+ * class is a configuration class that defines the mapping between standard
+ * {@link cn.org.codecrafters.simplejwt.constants.TokenAlgorithm} and the
+ * corresponding function implementation used by {@link
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver} for handling
+ * JWT algorithms. It enables developers to specify and customize the
+ * algorithm functions according to the chosen JWT algorithm and the library
+ * being used.
+ * </p>
+ *
+ * <p>
+ * The configuration options in this package help developers integrate and
+ * configure the {@link
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver} seamlessly
+ * into their Spring Boot applications. Developers can fine-tune the token
+ * resolution process and customize algorithm handling to align with their
+ * specific requirements and desired level of security.
+ * </p>
+ *
+ * <p>
+ * It is recommended to explore the classes in this package to understand how
+ * to configure and use the {@link
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver} effectively
+ * in the Spring Boot environment to handle JWT authentication and
+ * authorization securely and efficiently.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+
+package cn.org.codecrafters.simplejwt.authzero.config;
@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <h3>cn.org.codecrafters.simplejwt.authzero</h3>
+ *
+ * <p>
+ * This package contains classes related to the integration of the {@code
+ * com.auth0:java-jwt} library in the Simple JWT project. {@code 
+ * com.auth0:java-jwt} is a powerful and widely-used Identity as a Service
+ * (IDaaS) platform that provides secure authentication and authorization
+ * solutions for web and mobile applications. The classes in this package
+ * provide the necessary functionality to handle JSON Web Tokens (JWTs) using
+ * the {@code com.auth0:java-jwt} library.
+ * </p>
+ *
+ * <p>
+ * The main class in this package is the {@link 
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}, which
+ * implements the {@link cn.org.codecrafters.simplejwt.TokenResolver} interface
+ * and uses the {@code com.auth0:java-jwt} library to handle JWT operations. It
+ * provides the functionality to create, validate, and extract JWTs using the
+ * {@code com.auth0:java-jwt} library. Developers can use this class as the
+ * main token resolver in the Simple JWT project when integrating {@code
+ * com.auth0:java-jwt} as the JWT management library.
+ * </p>
+ *
+ * <p>
+ * The {@code AuthzeroTokenResolver} relies on the {@code com.auth0:java-jwt}
+ * library to handle the underlying JWT operations, including token creation,
+ * validation, and extraction. It utilizes the {@code com.auth0:java-jwt}
+ * {@code Algorithm} class to define and use different algorithms for JWT
+ * signing and verification.
+ * </p>
+ *
+ * <p>
+ * To use the {@code AuthzeroTokenResolver}, developers must provide the
+ * necessary configurations and dependencies, such as the {@code GuidCreator}
+ * for generating unique JWT IDs (JTI), the supported algorithm function, the
+ * issuer name, and the secret key used for token signing and validation. The
+ * {@code AuthzeroTokenResolverConfig} class provides a convenient way to
+ * configure these dependencies.
+ * </p>
+ *
+ * <p>
+ * Developers using the {@code com.auth0:java-jwt} integration should be
+ * familiar with the concepts and usage of the {@code com.auth0:java-jwt}
+ * library and follow the official {@code com.auth0:java-jwt} documentation for
+ * best practices and security considerations.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+
+package cn.org.codecrafters.simplejwt.authzero;
@@ -20,17 +20,21 @@ package cn.org.codecrafters.simplejwt;
 import java.util.Map;

 /**
+ * <p>
 * TokenPayload - Interface for JWT Payload Data Classes.
+ * </p>
 * <p>
 * The {@code TokenPayload} interface is used to mark a data class as suitable
 * for being used as the payload in a JSON Web Token (JWT). Any class
 * implementing this interface can be used to represent the payload data that
 * will be included in a JWT.
+ * </p>
 * <p>
 * Implementing this interface indicates that the data class contains
 * information that needs to be securely transmitted and verified as part of a
 * JWT. The payload typically contains claims or attributes that provide
 * additional information about the JWT subject or context.
+ * </p>
 * <p>
 * <b>Usage:</b>
 * To use a class as a JWT payload, simply implement the {@code TokenPayload}
@@ -40,6 +44,7 @@ import java.util.Map;
 *     // Class implementation with payload data...
 * }
 * </pre>
+ * </p>
 *
 * @since 1.0.0
 * @version 1.0.0
@@ -21,26 +21,31 @@ import java.time.Duration;
 import java.util.Map;

 /**
+ * <p>
 * The {@code TokenResolver} interface defines methods for creating,
 * extracting, and renewing tokens, particularly JSON Web Tokens (JWTs). It
 * provides a set of methods to generate tokens with various payload
 * configurations, extract payloads from tokens, and renew expired tokens.
+ * </p>
 * <p>
 * <b>Token Creation:</b>
 * The interface provides overloaded methods for creating tokens with different
 * payload configurations, including expiration time, audience, subject, and
 * custom payload data. Clients can choose the appropriate method based on
 * their specific token requirements.
+ * </p>
 * <p>
 * <b>Token Extraction:</b>
 * The interface includes methods to extract payload information from a given
 * token. Clients can use these methods to obtain the payload data encoded in
 * the token.
+ * </p>
 * <p>
 * <b>Token Renewal:</b>
 * The interface also offers methods for token renewal. Clients can renew an
 * expired token by providing a new expiration time, audience, subject, and
 * optional custom payload data.
+ * </p>
 *
 * @param <ResolvedTokenType> the type of the result obtained by the
 *                            third-party library when parsing JWTs
@@ -30,6 +30,7 @@ import java.lang.annotation.Target;
 * excluded from being automatically injected into the JSON Web Token (JWT)
 * payload during token generation. When a property is annotated with this
 * annotation, it will not be included as part of the JWT payload.
+ * </p>
 *
 * <p><b>Usage:</b>
 * To exclude a property from the JWT payload, annotate the property with
@@ -40,18 +41,20 @@ import java.lang.annotation.Target;
 *     private String username;
 *
 *     // This property will not be included in the JWT payload
- *     {@literal @}ExcludeFromPayload
+ *     @ExcludeFromPayload
 *     private String sensitiveData;
 *
 *     // Getters and setters...
 * }
 * }</pre>
+ * </p>
 *
 * <p><b>Note:</b>
 * This annotation should be used only on properties that are not intended to
 * be included in the JWT payload due to their sensitive nature or for other
 * reasons. It is important to carefully choose which properties are excluded
 * from the payload to ensure the JWT remains secure and efficient.
+ * </p>
 *
 * @since 1.0.0
 * @version 1.0.0
@@ -20,13 +20,16 @@ package cn.org.codecrafters.simplejwt.config;
 import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;

 /**
+ * <p>
 * The TokenResolverConfig interface provides a mechanism to configure a
 * TokenResolver with algorithm functions.
+ * </p>
 * <p>
 * This generic interface is used to define the configuration details for a
 * TokenResolver that utilizes algorithm functions. The interface allows for
 * specifying algorithm functions corresponding to different TokenAlgorithm
 * instances supported by the TokenResolver implementation.
+ * </p>
 *
 * @param <AlgorithmFunction> the type representing algorithm functions used by
 *                            the TokenResolver
@@ -16,8 +16,20 @@
 */

 /**
- * The package provides all exceptions be used by module guid.
+ * <p>
+ * The classes in this package provide configuration options and settings for
+ * the Simple JWT library. They are used to customize the behavior of the
+ * library and allow developers to fine-tune various aspects of JWT generation
+ * and validation.
+ * </p>
+ *
+ * <p>
+ * Other configuration classes may be added in the future to support additional
+ * customization options and features. Developers using the Simple JWT library
+ * should be familiar with the available configuration options to ensure proper
+ * integration and usage of the library.
+ * </p>
 *
 * @since 1.0.0
 */
-package cn.org.codecrafters.devkit.guid.exceptions;
+package cn.org.codecrafters.simplejwt.config;
@@ -20,12 +20,47 @@ package cn.org.codecrafters.simplejwt.constants;
 import java.util.List;

 /**
- * PredefinedKeys
+ * <p>
+ * This class contains predefined keys that are commonly used in JSON Web
+ * Tokens (JWT).
+ * </p>
 *
- * @author Zihlu Wang
+ * <p>
+ * JWTs consist of a set of claims represented as key-value pairs. These claims
+ * store various pieces of information, such as the subject, issuer, expiration
+ * time, and more. To ensure consistency and avoid spelling mistakes, this
+ * class provides constants for the standard keys used in JWT claims.
+ * </p>
+ *
+ * <p>
+ * Developers using this JWT library can use these predefined keys to set and
+ * retrieve claims in a safer and more readable way. By using constants instead
+ * of plain strings, it helps prevent typos and makes the code more
+ * maintainable.
+ * </p>
+ *
+ * @since 1.0.0
 */
 public final class PredefinedKeys {

-    public static final List<String> KEYS = List.of("aud", "sub", "nbf", "iss", "exp", "iat", "jti");
+    // Constants for standard JWT claims
+    public static final String ISSUER = "iss";

+    public static final String SUBJECT = "sub";
+
+    public static final String AUDIENCE = "aud";
+
+    public static final String EXPIRATION_TIME = "exp";
+
+    public static final String NOT_BEFORE = "nbf";
+
+    public static final String ISSUED_AT = "iat";
+
+    public static final String JWT_ID = "jti";
+
+    private PredefinedKeys() {
+        // Private constructor to prevent instantiation
+    }
+
+    public static final List<String> KEYS = List.of(ISSUER, SUBJECT, AUDIENCE, EXPIRATION_TIME, NOT_BEFORE, ISSUED_AT, JWT_ID);
 }
@@ -17,21 +17,16 @@

 package cn.org.codecrafters.simplejwt.constants;

-import ch.qos.logback.core.subst.Token;
 import lombok.Getter;

-import java.lang.reflect.Array;
-import java.util.Arrays;
-import java.util.List;
-import java.util.stream.Stream;
-
 /**
+ * <p>
 * The {@code TokenAlgorithm} enum class defines the algorithms that can be
 * used for signing and verifying JSON Web Tokens (JWT). JWT allows various
 * cryptographic algorithms to be used for secure token generation and
 * validation. This enum provides a list of supported algorithms to ensure
 * consistent usage and avoid potential security issues.
- *
+ * </p>
 * <p><b>Supported Algorithms:</b>
 * This enum includes the following supported algorithms:
 * <ul>
@@ -45,9 +40,10 @@ import java.util.stream.Stream;
 *     <li>{@link TokenAlgorithm#ES384}: ECDSA with SHA-384</li>
 *     <li>{@link TokenAlgorithm#ES512}: ECDSA with SHA-512</li>
 * </ul>
+ * </p>
 *
- * @since 1.0.0
 * @version 1.0.0
+ * @since 1.0.0
 */
@Getter
 public enum TokenAlgorithm {
@@ -18,18 +18,21 @@
 package cn.org.codecrafters.simplejwt.exceptions;

 /**
+ * <p>
 * This {@code UnsupportedAlgorithmException} is to indicates that the given
 * algorithm is not supported by TokenResolver yet.
+ * </p>
 * <p>
 * To support a specified algorithm, you could
+ * </p>
 *
 * @author Zihlu Wang
 */
 public class UnsupportedAlgorithmException extends RuntimeException {

    /**
-     * Constructs a new runtime exception with {@code null} as its
-     * detail message.  The cause is not initialized, and may subsequently be
+     * Constructs a new runtime exception with {@code null} as its detail
+     * message. The cause is not initialized, and may subsequently be
     * initialized by a call to {@link #initCause}.
     */
    public UnsupportedAlgorithmException() {
@@ -48,10 +51,14 @@ public class UnsupportedAlgorithmException extends RuntimeException {
    }

    /**
+     * <p>
     * Constructs a new runtime exception with the specified detail message and
-     * cause.  <p>Note that the detail message associated with
+     * cause.
+     * </p>
+     * <p>Note that the detail message associated with
     * {@code cause} is <i>not</i> automatically incorporated in
     * this runtime exception's detail message.
+     * </p>
     *
     * @param message the detail message (which is saved for later retrieval
     *                by the {@link #getMessage()} method).
@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <p>
+ * The {@code cn.org.codecrafters.simplejwt.exceptions} package contains
+ * custom exception classes related to the Simple JWT library. These
+ * exceptions are thrown when there are issues or errors during the generation
+ * , validation, or processing of JSON Web Tokens (JWTs) in Java applications.
+ * </p>
+ *
+ * <p>
+ * Custom exception classes in this package are designed to enhance the
+ * robustness and reliability of the JWT handling process by providing clear
+ * and meaningful error messages to the developers. They help developers
+ * identify and troubleshoot issues related to JWT generation, validation, or
+ * extraction and ensure smooth operation and error handling in their
+ * applications.
+ * </p>
+ *
+ * <p>
+ * Developers using the Simple JWT library should be aware of the possible
+ * exceptions that can be thrown and handle them appropriately to ensure secure
+ * and reliable JWT handling in their Java applications.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+package cn.org.codecrafters.simplejwt.exceptions;
@@ -16,8 +16,30 @@
 */

 /**
- * package-info
+ * <p>
+ * The {@code cn.org.codecrafters.simplejwt} package is the core package of the
+ * Simple JWT project, which provides a lightweight and easy-to-use library for
+ * working with JSON Web Tokens (JWTs) in Java applications. JWT is a
+ * widely-used standard for representing claims between two parties, typically
+ * used to secure web and mobile applications. This library aims to simplify
+ * the JWT handling process and provide convenient abstractions for JWT
+ * generation, validation, and extraction.
+ * </p>
 *
- * @author Zihlu Wang
+ * <p>
+ * The Simple JWT library is designed to be flexible and customizable, allowing
+ * developers to use different algorithms, token resolvers, and token payload
+ * classes based on their specific application requirements. It aims to
+ * simplify the JWT handling process while maintaining security and best
+ * practices for working with JWTs.
+ * </p>
+ *
+ * <p>
+ * Developers should refer to the official documentation and examples for the
+ * Simple JWT project to understand how to use the library effectively and
+ * securely in their Java applications.
+ * </p>
+ *
+ * @since 1.0.0
 */
 package cn.org.codecrafters.simplejwt;
@@ -15,11 +15,12 @@
 * limitations under the License.
 */

-package cn.org.codecrafters.simplejwt;
+package cn.org.codecrafters.simplejwt.autoconfiguration;

-import cn.org.codecrafters.devkit.guid.GuidCreator;
+import cn.org.codecrafters.guid.GuidCreator;
+import cn.org.codecrafters.simplejwt.TokenResolver;
 import cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver;
-import cn.org.codecrafters.simplejwt.properties.SimpleJwtProperties;
+import cn.org.codecrafters.simplejwt.autoconfiguration.properties.SimpleJwtProperties;
 import com.auth0.jwt.interfaces.DecodedJWT;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -33,35 +34,91 @@ import org.springframework.context.annotation.Configuration;
 import java.util.UUID;

 /**
- * SimpleJwtAutoConfiguration
+ * <p>
+ * SimpleJwtAutoConfiguration is responsible for automatically configuring the
+ * Simple JWT library when used in a Spring Boot application. It provides
+ * default settings and configurations to ensure that the library works
+ * smoothly without requiring manual configuration.
+ * </p>
+ *
+ * <p>
+ * This auto-configuration class sets up the necessary beans and components
+ * required for JWT generation and validation. It automatically creates and
+ * configures the {@link TokenResolver} bean based on the available options and
+ * properties.
+ * </p>
+ *
+ * <p>
+ * Developers using the Simple JWT library with Spring Boot do not need to
+ * explicitly configure the library, as the auto-configuration takes care of
+ * setting up the necessary components and configurations automatically.
+ * However, developers still have the flexibility to customize the behavior of
+ * the library by providing their own configurations and properties.
+ * </p>
 *
 * @author Zihlu Wang
+ * @version 1.0.0
+ * @since 1.0.0
 */
@Slf4j
@Configuration
@EnableConfigurationProperties(value = {SimpleJwtProperties.class})
 public class SimpleJwtAutoConfiguration {

+    /**
+     * The GuidCreator instance to be used for generating JWT IDs (JTI).
+     */
    private GuidCreator<?> jtiCreator;

+    /**
+     * Sets the GuidCreator instance to be used for generating JWT IDs (JTI).
+     *
+     * @param jtiCreator the {@code GuidCreator} instance
+     */
    @Autowired
    public void setJtiCreator(GuidCreator<?> jtiCreator) {
        this.jtiCreator = jtiCreator;
    }

+    /**
+     * The {@code SimpleJwtProperties} instance containing the configuration
+     * properties for Simple JWT.
+     */
    private final SimpleJwtProperties simpleJwtProperties;

+    /**
+     * Constructs a new {@code SimpleJwtAutoConfiguration} instance with the
+     * provided SimpleJwtProperties.
+     *
+     * @param simpleJwtProperties the SimpleJwtProperties instance
+     */
    @Autowired
    public SimpleJwtAutoConfiguration(SimpleJwtProperties simpleJwtProperties) {
        this.simpleJwtProperties = simpleJwtProperties;
    }

+    /**
+     * Creates a new {@code GuidCreator} bean if no existing bean with the name
+     * "jtiCreator" is found. The created {@code GuidCreator} is used for
+     * generating JWT IDs (JTI).
+     *
+     * @return the GuidCreator instance
+     */
    @Bean
    @ConditionalOnMissingBean(value = GuidCreator.class, name = "jtiCreator")
    public GuidCreator<?> jtiCreator() {
        return (GuidCreator<UUID>) UUID::randomUUID;
    }

+    /**
+     * Creates a new {@link TokenResolver} bean using {@link
+     * AuthzeroTokenResolver} if no existing {@link TokenResolver} bean is
+     * found. The {@link AuthzeroTokenResolver} is configured with the
+     * provided {@link GuidCreator}, {@code algorithm}, {@code issuer}, and
+     * {@code secret} properties from {@link SimpleJwtProperties}.
+     *
+     * @return the {@link TokenResolver} instance
+     */
    @Bean
    @ConditionalOnClass({DecodedJWT.class, AuthzeroTokenResolver.class})
    @ConditionalOnMissingBean({TokenResolver.class})
@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <p>
+ * The classes in this package are responsible for automatically configuring
+ * the Simple JWT library when it is used in a Spring Boot application. They
+ * provide default settings and configurations to ensure that the library works
+ * smoothly and seamlessly without requiring developers to manually configure
+ * it.
+ * </p>
+ *
+ * <p>
+ * Developers using the Simple JWT library with Spring Boot do not need to
+ * explicitly configure the library, as the auto-configuration classes take
+ * care of setting up the necessary components and configurations
+ * automatically. However, developers still have the flexibility to customize
+ * the behavior of the library by providing their own configurations and
+ * properties.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+package cn.org.codecrafters.simplejwt.autoconfiguration;
@@ -0,0 +1,96 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package cn.org.codecrafters.simplejwt.autoconfiguration.properties;
+
+import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * <p>
+ * {@code SimpleJwtProperties} is a configuration properties class used to
+ * store the properties related to Simple JWT library configuration. These
+ * properties can be configured in the application's properties file (e.g.,
+ * application.properties) with the prefix "code-crafters.simple-jwt".
+ * </p>
+ *
+ * <p>
+ * SimpleJwtProperties provides configuration options for the JWT algorithm,
+ * issuer, and secret. The properties are used by the {@link
+ * cn.org.codecrafters.simplejwt.autoconfiguration.SimpleJwtAutoConfiguration}
+ * class to set up the necessary configurations for JWT generation and
+ * validation.
+ * </p>
+ *
+ * <p>
+ * Developers can customize the JWT algorithm, issuer, and secret by setting
+ * the corresponding properties in the application's properties file. The
+ * SimpleJwtAutoConfiguration class reads these properties and uses them to
+ * create the TokenResolver bean with the desired configuration.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+@Data
+@ConfigurationProperties(prefix = "code-crafters.simple-jwt")
+public class SimpleJwtProperties {
+
+    /**
+     * The algorithm used for JWT generation and validation.
+     */
+    private TokenAlgorithm algorithm;
+
+    /**
+     * The issuer value to be included in the generated JWT.
+     */
+    private String issuer;
+
+    /**
+     * The secret key used for JWT generation and validation.
+     */
+    private String secret;
+
+    /**
+     * Returns the JWT algorithm configured in the properties.
+     *
+     * @return the JWT algorithm
+     */
+    public final TokenAlgorithm algorithm() {
+        return algorithm;
+    }
+
+    /**
+     * Returns the issuer value configured in the properties.
+     *
+     * @return the issuer value
+     */
+    public final String issuer() {
+        return issuer;
+    }
+
+    /**
+     * Returns the secret key configured in the properties.
+     *
+     * @return the secret key
+     */
+    public final String secret() {
+        return secret;
+    }
+
+}
+
@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <p>
+ * The "cn.org.codecrafters.simplejwt.autoconfiguration.properties" package
+ * contains configuration properties classes used for Simple JWT library
+ * auto-configuration. These classes define the properties that can be
+ * configured in the application's properties file (e.g.,
+ * application.properties) to customize the behavior and settings of the Simple
+ * JWT library.
+ * </p>
+ *
+ * <p>
+ * Developers can customize the JWT algorithm, issuer, and secret by setting
+ * the corresponding properties in the application's properties file with the
+ * prefix "code-crafters.simple-jwt". The SimpleJwtAutoConfiguration class
+ * reads these properties and uses them to create the {@link
+ * cn.org.codecrafters.simplejwt.TokenResolver} bean with the desired
+ * configuration.
+ * </p>
+ *
+ * @since 1.0.0
+ */
+package cn.org.codecrafters.simplejwt.autoconfiguration.properties;
@@ -1,53 +0,0 @@
-/*
- * Copyright (C) 2023 CodeCraftersCN.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- *
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package cn.org.codecrafters.simplejwt.properties;
-
-import cn.org.codecrafters.devkit.guid.GuidCreator;
-import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
-import lombok.Data;
-import lombok.Getter;
-import org.springframework.boot.context.properties.ConfigurationProperties;
-
-/**
- * SimpleJwtProperties
- *
- * @author Zihlu Wang
- */
-@Data
-@ConfigurationProperties(prefix = "code-crafters.simple-jwt")
-public class SimpleJwtProperties {
-
-    private TokenAlgorithm algorithm;
-
-    private String issuer;
-
-    private String secret;
-
-    public final TokenAlgorithm algorithm() {
-        return algorithm;
-    }
-
-    public final String issuer() {
-        return issuer;
-    }
-
-    public final String secret() {
-        return secret;
-    }
-
-}
@@ -1,44 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  ~ Copyright (C) 2023 CodeCraftersCN.
-  ~
-  ~ Licensed under the Apache License, Version 2.0 (the "License");
-  ~ you may not use this file except in compliance with the License.
-  ~ You may obtain a copy of the License at
-  ~
-  ~     http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing, software
-  ~ distributed under the License is distributed on an "AS IS" BASIS,
-  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  ~
-  ~ See the License for the specific language governing permissions and
-  ~ limitations under the License.
-  -->
-
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-    <parent>
-        <groupId>cn.org.codecrafters</groupId>
-        <artifactId>jdevkit</artifactId>
-        <version>1.0.0</version>
-    </parent>
-
-    <artifactId>sms-sender-facade</artifactId>
-
-    <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    </properties>
-
-    <dependencies>
-        <dependency>
-            <groupId>cn.org.codecrafters</groupId>
-            <artifactId>devkit-core</artifactId>
-        </dependency>
-    </dependencies>
-
-</project>