{"id":22441200,"url":"https://github.com/imshawan/spring-rest-service","last_synced_at":"2026-04-13T22:03:30.265Z","repository":{"id":266657619,"uuid":"898953719","full_name":"imshawan/spring-rest-service","owner":"imshawan","description":"A boilerplate project to kickstart Spring Boot applications with standardized setups, including uniform response structures, error handling, and modular design.","archived":false,"fork":false,"pushed_at":"2024-12-13T08:43:34.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T09:49:32.803Z","etag":null,"topics":["java","java-rest-api","maven","rest-api","spring-boot","spring-mvc","spring-security"],"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/imshawan.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}},"created_at":"2024-12-05T10:53:44.000Z","updated_at":"2024-12-13T08:43:38.000Z","dependencies_parsed_at":"2025-02-07T16:45:36.527Z","dependency_job_id":null,"html_url":"https://github.com/imshawan/spring-rest-service","commit_stats":null,"previous_names":["imshawan/spring-rest"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/imshawan/spring-rest-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imshawan%2Fspring-rest-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imshawan%2Fspring-rest-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imshawan%2Fspring-rest-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imshawan%2Fspring-rest-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imshawan","download_url":"https://codeload.github.com/imshawan/spring-rest-service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imshawan%2Fspring-rest-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31772643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["java","java-rest-api","maven","rest-api","spring-boot","spring-mvc","spring-security"],"created_at":"2024-12-06T02:13:22.370Z","updated_at":"2026-04-13T22:03:30.248Z","avatar_url":"https://github.com/imshawan.png","language":"Java","readme":"# Spring REST Service\n\nA comprehensive boilerplate project designed to accelerate the development of Spring Boot applications. This starter comes equipped with essential configurations, reusable components, and modular architecture to provide a seamless starting point for new developers and teams.\n\nThe project emphasizes standardized practices, robust error handling, and scalability, making it ideal for building production-grade REST APIs. Additionally, it includes prebuilt modules for user onboarding and file upload services, enabling faster implementation of common features without reinventing the wheel.\n\n## Features\n\n### What comes Out-of-the-box?\n\nThis starter project provides a ready-to-use setup for quickly bootstrapping Spring Boot applications with:\n\n1. Standardized API Responses\n\n   - Success responses via `ApiResponse` class.\n   - Error responses via `HTTPError` class.\n   - Prebuilt User Onboarding Service\n\n2. Basic user management functionality (e.g., user registration, login).\n\n   - Extendable design for adding authentication or user roles.\n   - File Upload Service\n   - JWT authentication and validation layers\n   - CORS implementation\n\n3. Custom exception handlers to manage and format application-level and system-level errors.\n\n4. Preconfigured connection to MongoDB for easy database integration.\n\n   - Spring Data MongoDB setup for seamless interaction with MongoDB collections.\n   - Environment Configurations\n\n5. Modular and Scalable Architecture - adheres to Spring best practices for clean code, modularity, and scalability.\n6. RESTful Standards\n\n   - Preconfigured REST controllers and response formats to follow REST best practices.\n     Security Placeholder.\n   - Global Exception Handling\n\n7. API Layer Abstraction\n   - Service layer abstraction for better separation of concerns and testability.\n   - Placeholder for Swagger Integration\n\n## Setup and Installation\n\n### Prerequisites\n\n- Java 21 or higher installed\n- Spring Boot 3.4.0\n- Maven 3.8.1 or higher installed\n- MongoDB Atlas or Local server set up\n\n### Steps\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/imshawan/spring-rest-service.git\ncd spring-rest-service\n```\n\n2. Configure the application properties:\n   Update the database configuration in src/main/resources/application.properties:\n\n```properties\nspring.application.name=spring-rest\nspring.data.mongodb.uri=\nspring.data.mongodb.database=RestStarterDb\nspring.web.resources.static-locations=classpath:/static/,file:uploads/\nserver.port=8080\nlogging.level.org.mongodb.driver=warn\njwt.secret=your-secret-key\njwt.expiration=3600000\ncors.allowedOrigins=http://localhost:8005,http://localhost:8000\n```\n\n3. Build and run the application:\n\n```bash\nmvn clean install\nmvn spring-boot:run\n```\n\n4. Access the application:\n\nBase URL: `http://localhost:8080`\n\n5. Access Swagger API documentation:\n\nSwagger documentation will be available at `http://localhost:8080/swagger-ui/index.html` after starting the application.\n\n## API Endpoints\n\n| HTTP Method | Endpoint                              | Description                                      | Request Body                                          | Response                                     |\n| ----------- | ------------------------------------- | ------------------------------------------------ | ----------------------------------------------------- | -------------------------------------------- |\n| `POST`      | `/api/files/upload`                   | Upload a file to the server.                     | `file`: Multipart file                                | Success message with file info.              |\n| `POST`      | `/api/users/register`                 | Register a new user.                             | JSON with `username`, `email`, `fullname`, `password` | Success message with user info.              |\n| `POST`      | `/api/users/signin`                   | Sign in an existing user and return a JWT token. | JSON with `username/email` and `password`             | Success message with user data and token.    |\n| `GET`       | `/api/users/{id}`                     | Fetch user profile by user ID.                   | N/A                                                   | User profile data or 404 if not found.       |\n| `PUT`       | `/api/users/{id}`                     | Update user profile by user ID.                  | JSON with user data                                   | Updated user data or 404 if not found.       |\n| `DELETE`    | `/api/users/{id}`                     | Delete user profile by user ID.                  | N/A                                                   | 204 No Content if deleted, 404 if not found. |\n| `POST`      | `/api/users/profile/{userId}/picture` | Upload profile picture for the user.             | `file`: Multipart file                                | Success message with file info.              |\n\n### Response Handlers\n\n#### Success Response\n\nThe `ApiResponse` class is used to standardize successful responses.\nExample:\n\n```json\n{\n  \"message\": \"Data retrieved successfully\",\n  \"status\": 200,\n  \"path\": \"/api/users/123\",\n  \"statusMessage\": \"OK\",\n  \"data\": {\n    \"key\": \"value\"\n  }\n}\n```\n\n#### Error Response\n\nThe `HTTPError` class encapsulates error details for failed HTTP requests.\n\nExample:\n\n```json\n{\n  \"message\": \"Invalid input data\",\n  \"status\": 400,\n  \"path\": \"/api/users/register\",\n  \"statusMessage\": \"Bad Request\"\n}\n```\n\n## Swagger Integration\n\nSwagger has been implemented to provide detailed API documentation and testing interface.\n\n- Swagger Configuration: The project includes a preconfigured Swagger setup to auto-generate documentation for the defined REST API endpoints.\n\n- Accessing Swagger UI: Navigate to `http://localhost:8080/swagger-ui/index.html` to interactively explore and test the APIs.\n\nSwagger setup is located in `OpenAPIConfig` class, ensuring all endpoints are documented and available for testing.\n\n## **Contributing**\n\nWe welcome contributions to this project! If you'd like to contribute, please follow these steps:\n\n1. **Fork the repository**: Create your own fork of the project on GitHub.\n2. **Clone the repository**: Clone your fork to your local machine to work on it.\n   ```bash\n   git clone https://github.com/imshawan/spring-rest-service.git\n   ```\n3. **Create a new branch**: Create a new branch to work on your changes.\n   ```bash\n   git checkout -b your-branch-name\n   ```\n4. **Make changes**: Implement your feature, fix a bug, or improve the documentation.\n5. **Commit changes**: Commit your changes with a descriptive commit message.\n   ```bash\n   git commit -m \"Describe your changes\"\n   ```\n6. **Push changes**: Push your changes to your forked repository.\n   ```bash\n   git push origin your-branch-name\n   ```\n7. **Create a pull request**: Go to the original repository and create a pull request from your branch. Provide a detailed description of the changes you've made.\n\n### **Guidelines**:\n\n- Ensure your code follows the existing code style and conventions.\n- Write clear commit messages.\n- Ensure all tests pass before submitting a pull request.\n- Be respectful and considerate when interacting with the community.\n\n## **To-Do**\n\n- [x] Implement Swagger for API documentation\n- [ ] Add unit and integration tests\n- [ ] Enhance error handling and logging\n\n## **License**\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n## **Author**\n\nThis project is maintained by [Shawan Mandal](https://github.com/imshawan).\n\nIf you have any questions or suggestions, feel free to reach out via GitHub or at [github@imshawan.dev](mailto:github@imshawan.dev).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimshawan%2Fspring-rest-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimshawan%2Fspring-rest-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimshawan%2Fspring-rest-service/lists"}