{"id":24750772,"url":"https://github.com/Yassinekrn/Advanced-Spring-Boot-Blog-API","last_synced_at":"2025-10-10T20:32:14.633Z","repository":{"id":274504522,"uuid":"922540250","full_name":"Yassinekrn/Advanced-Spring-Boot-Blog-API","owner":"Yassinekrn","description":"A scalable Spring Boot Blog REST API for efficient content management, featuring secure authentication, post and comment management, and detailed API docs. Built with industry best practices, it offers clean, maintainable code, ideal for developers seeking a high-quality Spring Boot project.","archived":false,"fork":false,"pushed_at":"2025-02-02T17:23:26.000Z","size":84,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T15:08:36.341Z","etag":null,"topics":["blog-platform","crud","docker","exception-handling","jwt-authentication","model-mapper","pagination","restful-api","role-based-access-control","search-functionality","spring-boot","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yassinekrn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-26T13:46:38.000Z","updated_at":"2025-02-02T17:37:03.000Z","dependencies_parsed_at":"2025-02-02T15:24:14.529Z","dependency_job_id":"1855fe5f-c51a-44b0-960d-0a525f1921be","html_url":"https://github.com/Yassinekrn/Advanced-Spring-Boot-Blog-API","commit_stats":null,"previous_names":["yassinekrn/real-time-api-spring-boot","yassinekrn/advanced-spring-boot-blog-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yassinekrn/Advanced-Spring-Boot-Blog-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yassinekrn%2FAdvanced-Spring-Boot-Blog-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yassinekrn%2FAdvanced-Spring-Boot-Blog-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yassinekrn%2FAdvanced-Spring-Boot-Blog-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yassinekrn%2FAdvanced-Spring-Boot-Blog-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yassinekrn","download_url":"https://codeload.github.com/Yassinekrn/Advanced-Spring-Boot-Blog-API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yassinekrn%2FAdvanced-Spring-Boot-Blog-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005271,"owners_count":26083863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog-platform","crud","docker","exception-handling","jwt-authentication","model-mapper","pagination","restful-api","role-based-access-control","search-functionality","spring-boot","swagger"],"created_at":"2025-01-28T09:08:52.844Z","updated_at":"2025-10-10T20:32:14.628Z","avatar_url":"https://github.com/Yassinekrn.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Boot Real-Time API\n\nA robust and scalable Spring Boot application offering real-time API services with user authentication, post and comment management, and advanced security features. Built with industry best practices, this project is ideal for developers who want a production-ready API backend with a clean and maintainable codebase.\n\n---\n\n-   [Features ✨](#features)\n-   [Project Structure 📁](#project-structure)\n-   [Getting Started 🏁](#getting-started)\n-   [Configuration ⚙️](#configuration)\n-   [API Documentation 📖](#api-documentation)\n-   [Testing 🧪](#testing)\n-   [Deployment 🚀](#deployment)\n-   [Contributing 🤝](#contributing)\n-   [License 📄](#license)\n\n---\n\n## Features ✨\n\n### User Authentication and Authorization 🔐\n\n-   **JWT-based authentication** for secure stateless sessions.\n-   **Role-based access control** with Admin and User roles.\n-   Endpoints for **user registration** and **login**.\n\n### Post Management 📝\n\n-   **CRUD operations** for blog posts.\n-   **Pagination \u0026 sorting** for efficient listing.\n-   **Search functionality** to find posts by title or description.\n\n#### AI-Powered Enhancements 🤖\n\n-   **AI-driven content summarization** using locally hosted ollama LLM.\n\n### Comment Management 💬\n\n-   **CRUD operations** for comments.\n-   Fetch comments by **post ID**.\n-   Ensure comments belong to the correct post.\n-   **Role-based permissions** for comment operations.\n\n### User Management 👥\n\n-   **CRUD operations** for user profiles.\n-   **Role assignment** for better access control.\n-   Retrieve detailed user information.\n\n### Security 🔒\n\n-   **JWT token generation** and validation.\n-   Custom user details service for authentication.\n-   **Configurable CORS settings** (using environment variables for domain management).\n-   **Rate limiting** to prevent abuse of API requests.\n\n### API Documentation 📖\n\n-   **Swagger/OpenAPI integration** for interactive API docs.\n-   Detailed annotations and summaries for each endpoint.\n\n### Configuration and Environment Management ⚙️\n\n-   **Externalized configuration** using a `.env` file and environment-specific properties.\n-   Easy management of database connections and other settings.\n\n### Exception Handling 🚨\n\n-   Custom exception classes for precise error reporting.\n-   Global exception handler to manage API error responses uniformly.\n\n### Database Interaction 🗄️\n\n-   **JPA repositories** for seamless database operations.\n-   Entity classes with **Hibernate ORM** for effective object-relational mapping.\n\n### Utility Services 🛠️\n\n-   **ModelMapper** for DTO and entity mapping.\n-   **BCrypt** for secure password encoding.\n\n### Testing 🧪\n\n-   **Postman collections** provided for API testing.\n-   **Swagger UI** for interactive endpoint testing.\n\n### Deployment and Build 🚀\n\n-   **Docker support** with a Dockerfile and docker-compose configuration.\n-   **Maven build configuration** for streamlined project management.\n\n### Logging and Monitoring 📊\n\n-   Configurable logging levels using **SLF4J** with **Logback**.\n-   **Actuator endpoints** for health checks and application metrics.\n\n### Industry Best Practices 🏆\n\n-   Clean, maintainable code following design patterns.\n-   Well-structured project organization for scalability and readability.\n\n---\n\n## Project Structure 📁\n\n```\n\napp/\n├── Dockerfile \u0026 docker-compose.yml # Docker support for containerized deployment 🚢\n├── pom.xml # Maven build configuration\n├── src/\n│ ├── main/\n│ │ ├── java/ # Application source code\n│ │ │ ├── config/ # Configuration classes (security, logging, rate limiting, etc.)\n│ │ │ ├── controllers/ # REST controllers (API endpoints)\n│ │ │ ├── entities/ # JPA entities mapping to database tables\n│ │ │ ├── exceptions/ # Custom exceptions and global error handling\n│ │ │ ├── implementations/ # Service implementations\n│ │ │ ├── payloads/ # Data Transfer Objects (DTOs)\n│ │ │ ├── repositories/ # JPA repository interfaces\n│ │ │ ├── security/ # Security components (JWT, authentication filters, etc.)\n│ │ │ ├── services/ # Business logic interfaces and implementations\n│ │ │ └── utils/ # Utility classes (constants, password encoder, etc.)\n│ │ └── resources/ # Application configurations (properties, logback, etc.)\n└── .mvn/ # Maven wrapper configuration\n\n```\n\n_Note: The folder structure is simplified for clarity. Each directory contains related files that keep the codebase modular and maintainable._\n\n---\n\n## Getting Started 🏁\n\n### Prerequisites\n\n-   **Java 17** or later\n-   **Maven**\n-   **Docker** (preferable, for containerized deployment)\n\n### Installation\n\n1. **Clone the repository:**\n\n    ```bash\n    git clone https://github.com/Yassinekrn/yassinekrn-real-time-api-spring-boot.git\n    cd yassinekrn-real-time-api-spring-boot\n    ```\n\n2. **Set up environment variables:**\n\n    Create a `.env` file in the root directory and add the following:\n\n    ```env\n    APP_JWT_SECRET=\u003cyour_secret_key\u003e\n    APP_JWT_EXPIRATION_IN_MS=\u003cduration_in_milliseconds\u003e\n    # Uncomment one of the following lines based on your environment\n    # OLLAMA_API_URL=http://localhost:11434/api/generate (for local development)\n    # OLLAMA_API_URL=http://host.docker.internal:11434/api/generate (for Docker)\n    OLLAMA_MODEL_NAME=\u003cmodel_name\u003e\n    CORS_ALLOWED_ORIGINS=https://frontend1.com,https://frontend2.com (must be comma-separated)\n    ```\n\n3. **Update `application.properties`:**\n\n    Before building the JAR file, ensure the following configuration is set:\n\n    ```properties\n    spring.datasource.url=jdbc:mysql://localhost:3306/blogdb?useSSL=false\u0026serverTimezone=UTC\n    ```\n\n    For Docker deployment, comment the above line and use:\n\n    ```properties\n    spring.datasource.url=jdbc:mysql://mysql-db:3306/blogdb\n    ```\n\n4. **Build the project using Maven:**\n\n    ```bash\n    ./mvn clean package\n    ```\n\n5. **Build and run Docker containers:**\n\n    ```bash\n    docker-compose build --no-cache\n    docker-compose down\n    docker-compose up -d\n    ```\n\n---\n\n## Configuration ⚙️\n\n### Environment Variables and custom configurations\n\n-   **CORS:** Configurable via environment variables to manage allowed domains. (refer to step 2 in the installation section)\n-   **Security:** JWT-based authentication is set up with role-based access. (only 2 roles are available by default: `ROLE_USER` and `ROLE_ADMIN`. also, please refer to step 2 in the installation section)\n-   **Rate Limiting:** Implemented using Bucket4j to prevent API abuse. (set to 10 requests per minute by default, could be changed in `RateLimitingFilterConfig.java`).\n\n_All configurations are managed via `application.properties` and the `.env` file._\n_You can also check the `utils/Constants.java` file for additional configuration constants._\n\n### Note on Admin Role 🛡️\n\nIf you want to add the admin role, you will need to manually insert it into the database.\n\nConnect to the database and run the following query:\n\n```sql\nINSERT INTO roles(name) VALUES('ROLE_ADMIN');\n```\n\n---\n\n## API Documentation 📖\n\nOnce the application is running, access the interactive API documentation via:\n\n```\nhttp://localhost:8080/swagger-ui.html\n```\n\nThis documentation is generated using **Swagger/OpenAPI** and provides comprehensive details for each endpoint.\n\n---\n\n## Testing 🧪\n\n-   **Postman Collection:** Import the provided Postman collection to test all endpoints.\n-   **Swagger UI:** Use the interactive Swagger UI for quick API testing and exploration.\n\n---\n\n## Deployment 🚀\n\n-   **Docker:** Use the provided `Dockerfile` and `docker-compose.yml` for containerized deployment.\n-   **Maven:** Standard Maven build process is used for project packaging.\n\n---\n\n## Contributing 🤝\n\nContributions are welcome! Please fork the repository and submit a pull request with your improvements.\n\n---\n\n## License 📄\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n---\n\n## Contact 📞\n\nFor inquiries or support, please contact:\n[krichenyassine22@gmail.com](mailto:krichenyassine22@gmail.com)\n[LinkedIn](https://www.linkedin.com/in/krichenyassine/)\n\n---\n\nEnjoy using the **Spring Boot Real-Time API** and happy coding! 🎉\n\n---\n\nMade with ❤️ by [Yassine Krichen](https://github.com/Yassinekrn)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYassinekrn%2FAdvanced-Spring-Boot-Blog-API","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYassinekrn%2FAdvanced-Spring-Boot-Blog-API","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYassinekrn%2FAdvanced-Spring-Boot-Blog-API/lists"}