- Welcome to Readers' Paradise - Your Bookish Heaven! 📚🏰
- This application is a library and order management system for a bookstore.
This application is designed for bookstores or libraries to manage their collection of books, categories, and user orders.
This application is the perfect tool for bookstore or library owners who want a simple and effective way to manage their book collection, user orders, and shopping cart inventory. It makes the process of purchasing and searching for books more convenient and organized for users. Therefore, this application provides many useful features for managing the book business and makes it easier for users to search for and order books.
- Programming Language : Java
- Framework: Spring Boot
- Spring Security and JWT: For authentication and security
- Springdoc OpenAPI: For OpenAPI documentation
- Logging System: Log4j2
- Testing: JUnit
- Database: MySQL
- Liquibase: For database version management
- Lombok: For boilerplate code generation
- MapStruct: For mapper generation
- Email: javax.mail
- Testcontainers: For integration tests with the H2 test database
- Retrieving a list of all library books with pagination support.
- Obtaining detailed book information using its unique identifier.
- Searching for books by title.
- Searching for books based on various parameters such as title, author, or genre.
- Getting a list of all available book categories.
- Accessing detailed category information using its unique identifier.
- Retrieving a list of books belonging to a specific category.
- Creating a new order.
- Receiving a list of all items in a specific order.
- Retrieving details of a specific order item using order and item identifiers.
- Adding a new product to a user's shopping cart.
- Obtaining the contents of a user's shopping cart.
- Updating the quantity of a product in the shopping cart.
- Removing a product from the shopping cart.
- Searching for books by title, author, or ISBN.
- Filtering books by categories.
For a better understanding, you can check out this short tutorial on how to register a new user and log in :
- https://www.loom.com/share/88084fa77e10417d80fcf3ad32beda23?sid=b27f4be2-fc16-43ca-8ebe-4842a0e4ba5a
- Use the POST method:
/api/auth/register
Example :
{
"email": "[email protected]",
"password": "securePassword123",
"repeatPassword": "securePassword123",
"firstName": "John",
"lastName": "Doe",
"shippingAddress": "123 Main St, City, Country "
}The expected response will include the user's identifier and other user-related information.
- User Authentication: 📌
- Use the POST method:
/api/auth/login.
Example :
{
"email": "[email protected]",
"password": "securePassword123"
}The expected response will contain an access token that needs to be used for further requests.
Request to search for books by an author: 📌
- Method: GET
- URL: http://localhost:8088/api/books/search?author=Taras%20Hryhorovych%20Shevchenko
- In this example, you are searching for books by the author "Taras Hryhorovych Shevchenko." The response to this request will contain a list of books that match your author query.
Request to view all categories (GET: /api/categories): 📌
- Method: GET
- URL: http://localhost:8088/api/categories
- This request allows you to retrieve a list of all book categories in your application.
Request to view a specific category by its unique identifier (GET: /api/categories/{id}): 📌
- Method: GET
- URL: http://localhost:8088/api/categories/{id}
- You can specify the unique identifier of the category in the URL, and this request will return detailed information about that category.
Request to get a list of books in a specific category (GET: /api/categories/{id}/books): 📌
- Method: GET
- URL: http://localhost:8088/api/categories/{id}/books
- In this example, you specify the unique identifier of the category in the URL, and this request will return a list of books that belong to that category.
Request to add an item to the user's cart (POST: /api/cart): 📌
- Here`s short video example : https://www.loom.com/share/e92806fe464c4ed18764431831c2a18a?t=22&sid=32f6aa81-26d0-44ca-bb7b-ac9206359f55
- Method: POST
- URL: http://localhost:8088/api/cart
- Example JSON request body:
{
"bookId": 2,
"quantity": 5
}- This request adds the specified item in the specified quantity to the user's cart.
Request to get a user's cart (GET: /api/cart): 📌
- Video example how to get info from user shopping cart : https://www.loom.com/share/5f832194408f4890bef6fd19e6f057cf?sid=dfae4dd4-eed5-4e7e-9e98-830c2d24e54c
- Method: GET
- URL: http://localhost:8088/api/cart
- This request allows you to retrieve the user's shopping cart along with the list of items in the cart. It returns detailed information about the cart and the items in it.
Request to update the quantity of an item in the user's cart (PUT: /api/cart/cart-items/{cartItemId}): 📌
- Method: PUT
- URL: http://localhost:8088/api/cart/cart-items/{cartItemId}
- Example JSON request body:
{
"quantity": 10
}- This request updates the quantity of a specific item in the user's cart.
Request to remove an item from the user's cart (DELETE: /api/cart/cart-items/{cartItemId}): 📌
- Method: DELETE
- URL: http://localhost:8088/api/orders
- This request place your order
Request to place your order (POST: api/orders): 📌
- Video example :
- https://www.loom.com/share/487c1133149e4c0a9aa08b559d88c37a?sid=5e4ba4b0-5d7a-4ef9-b885-5e56ab4c3489
- Method: POST
- URL: http://localhost:8088/api/orders
- This request place the order from the user's shopping cart based on its unique identifier
Request to view your placed order (POST: api/orders): 📌
- Video example :
- https://www.loom.com/share/a340f74a0ec347678844d9ed6b0bb314?sid=88acbd6b-dabf-46d7-aecb-914c2941826c
- Method: GET
- URL: http://localhost:8088/api/orders
- This request give an opportunity for user to check the order condition
If a user has the role ADMIN, they can utilize additional functionalities such as creating a new book, editing, and deleting an existing book. These requests will have endpoints /api/books/ and /api/books/{id} for creating, editing, and deleting, respectively.
- Utilizing the Access Token:
- After successful authentication, you will receive an access token.
- This access token should be included in the header of each request that requires authentication.
- It will be used to verify the user's rights and grant access to specific features.
- User Authentication and Authorization:
- The project provides user authentication based on their email and password using JSON Web Tokens (JWT).
- Spring Security is used to configure application security and protect resources.
- User Registration:
- Users can register, providing information including email and password.
- JWT Token Generation
- JWT tokens are used for secure user authentication and access control to protected resources.
- Email Validation:
- Implemented email format validation and verification for user emails.
- Logging:
- Log4j2 is used for logging actions and events within the application.
- Springdoc OpenAPI:
- Springdoc OpenAPI is used for automated API documentation generation.
- Password Encryption:
- BCrypt is used for secure storage and comparison of user passwords.
- Security Management:
- Security configuration using Spring Security to ensure data confidentiality and integrity.
- Integration Tests:
- Integration tests with Testcontainers to check component interactions, including interactions with the database.
- Data Validation:
- Data validation is used, including email format checking and password matching.
- Pagination Support for book and order listings.
- Ability to search for books using various criteria (title, author, genre, etc.).
- Management of book categories and their detailed information.
- Creation and management of user orders.
- Handling the contents of a user's shopping cart and updating the quantity of items in the cart.
The project includes email validation and password matching. For email validation, a custom annotation @Email is used, and for password matching, @MatchPassword annotation is used. Details can be found in respective classes.
The EmailValidator class is used for email validation. The @Email annotation is used to mark methods that accept email addresses. The validate() method is used for email address validation.
The PasswordMatcher class is used for password matching. The @MatchPassword annotation is used to mark methods that accept passwords. The matches() method is used for comparing two passwords.
Before starting work on the project, make sure you have the following components installed:
- 🔺 Java Development Kit (JDK) version 11 or higher.
- 🔺 Maven (4.0.0): Tool for project building and dependency management.
- 🔺 Git
- 🔺 MySQL: Database used for data storage.
- 🔺 Properly configured pom.xml file containing the following dependencies :
- For the detailed pom.xml file, you can find it in the project folder 📕.
Follow these steps to install and run the project:
- Clone the repository:
git clone [email protected]:RostyslavOnysh/book-store.git
- Ensure that Docker is installed on your system. You can configure the database parameters in the .env file. Make sure you have provided the correct information, such as the username, password, database name, and so on.
- Open a terminal and navigate to the root directory of your project.
- Run the application using Docker Compose. Use the following command:
docker-compose up-
This command will start containers for your application and the database in Docker.
-
After a successful launch, you can interact with your application's API. You can use tools like Postman or Swagger to interact with the API and verify its functionality.
-
User Registration
- Open Postman or another tool for sending HTTP requests.
- Create a POST request to /auth/register to register a new user. In the request body, provide the necessary information, such as email, password, first name, last name, and shipping address etc.
- Send the request, and the user will be registered.
- Using Swagger After successfully registering a user, you are ready to use Swagger for documenting and testing your API. You can follow these steps:
- Start your application and navigate to the URL where you have set up Swagger. This typically looks like http://your_server/api/swagger-ui/.
- You may be prompted for a login and password to authenticate in Swagger. Enter the login you used during registration (usually your email address), along with the corresponding password.
- Now you can use Swagger to view and test various endpoints of your API. Swagger provides a convenient interface for making requests and checking the functionality of your application.
Feel free to contact the author for any questions or feedback:
- Author: Rostyslav
This project is distributed under the MIT License. Feel free to modify and adapt it to your needs.