Skip to content

README.md

Latest commit

 

History

History
326 lines (230 loc) · 7.89 KB

README.md

File metadata and controls

326 lines (230 loc) · 7.89 KB

spring_boot_java_random_user

Spring Boot REST API that consumes the public Random User API and persists data in a PostgreSQL database. Interactive API documentation is available via Swagger UI / OpenAPI.

🛠️ Tech Stack

Technology Version
Java 25
Spring Boot 4.0.3
Spring Web MVC (managed by Boot)
Spring Data JDBC (managed by Boot)
Spring Actuator (managed by Boot)
springdoc-openapi 3.0.1
PostgreSQL 15
dotenv-java 5.2.2
Docker / Docker Compose -
Maven Wrapper included

📋 Prerequisites

  • Java 25+
  • Maven (or use the included ./mvnw wrapper)
  • Docker Desktop

⚙️ Configuration

1. Environment variables

Copy the template and fill in the values:

cp .env.template .env

.env content:

POSTGRES_USER={POSTGRES_USER}
POSTGRES_PASSWORD={POSTGRES_PASSWORD}
POSTGRES_DB={POSTGRES_DB}
POSTGRES_PORT={POSTGRES_PORT}

⚠️ The .env file is git-ignored. Never commit it.

2. Test properties

cp src/test/resources/application-test.properties.template src/test/resources/application-test.properties

⚠️ This file is also git-ignored. But for credentials and local overrides, use:

src/main/resources/application-local.properties

Example for application.properties

spring.application.name=spring_boot_java_random_user
springdoc.swagger-ui.path=/api
spring.datasource.url=jdbc:postgresql://localhost:5432/<database_name>
spring.datasource.driver-class-name=org.postgresql.Driver

Local credentials & security

To avoid exposing database credentials in source code, create a .env file at the project root.

Then, in src/main/resources/application-local.properties:

spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}

Both .env and application-local.properties are in .gitignore (already set).

To activate the local profile in IntelliJ or VS Code, add this environment variable to your run configuration:

SPRING_PROFILES_ACTIVE=local

This way, each developer can use their own credentials without risk of leaking them to GitHub.

⚠️ Common startup error:

Failed to configure a DataSource: 'url' attribute is not specified
and no embedded datasource could be configured.
Reason: Failed to determine a suitable driver class

This error occurs because the PostgreSQL driver is present in the dependencies but the datasource URL is not configured. Fix: either add the spring.datasource.* properties above, or exclude the DataSource auto-configuration if no database is needed:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

🚀 Running the project

Start the database

docker-compose up -d

With the Maven Wrapper (recommended)

./mvnw spring-boot:run

With Maven installed

mvn spring-boot:run

Build and run the JAR

./mvnw clean package
java -jar target/spring_boot_java_random_user-0.0.1-SNAPSHOT.jar

The application will be available at: http://localhost:8080

📖 API Documentation (Swagger UI)

http://localhost:8080/api

Raw OpenAPI specification (JSON):

http://localhost:8080/v3/api-docs

Available endpoints

Generate and persist random users

GET /random-users?count=500

Update an existing user

PUT /random-users/{id}
Content-Type: application/json

Example body:

{
  "gender": "female",
  "firstname": "Albert",
  "lastname": "Bing",
  "civility": "Mrs",
  "email": "albert.bing@example.com",
  "phone": "123456789",
  "picture": "pic.jpg",
  "nat": "FR"
}

Responses:

  • 200 if the user was updated successfully
  • 404 if the user id does not exist

🔍 Monitoring (Actuator)

http://localhost:8080/actuator
http://localhost:8080/actuator/health

🧪 Tests

The Maven plugin starts and stops Docker Compose automatically during tests:

./mvnw verify

Execution cycle:

  1. pre-integration-test → docker-compose up (PostgreSQL starts)
  2. integration-test → tests run
  3. post-integration-test → docker-compose down (PostgreSQL stops)

Prerequisite: Docker must be installed and running.

🔎 Code Quality (SonarQube)

A GitHub Actions workflow is configured in .github/workflows/sonar.yaml.

Workflow triggers

  • push on all branches
  • pull_request

What it runs

  • Java 25 setup (Temurin)
  • Maven build + tests + SonarQube analysis:
./mvnw clean verify sonar:sonar -Dsonar.qualitygate.wait=true

Required GitHub Secrets

| Secret | Description | | APPLICATION_TEST_PROPERTIES (Base64-encoded application-test.properties content) | SONAR_TOKEN | SonarQube authentication token | | SONAR_HOST_URL | SonarQube instance URL | | POSTGRES_USER | PostgreSQL user | | POSTGRES_PASSWORD | PostgreSQL password | | POSTGRES_DB | Database name | | POSTGRES_PORT | PostgreSQL port |

GITHUB_TOKEN is provided automatically by GitHub Actions.

JaCoCo coverage report (local)

./mvnw clean verify

Generated reports:

  • HTML: target/site/jacoco/index.html
  • XML (used by SonarQube): target/site/jacoco/jacoco.xml

📁 Project structure

src/
├── main/
│   ├── java/com/xpeho/spring_boot_java_random_user/
│   │   └── SpringBootJavaRandomUserApplication.java  ← Entry point, loads .env
│   └── resources/
│       ├── application.properties                    ← Spring configuration
│       └── schema.sql                                ← Database schema
└── test/
    ├── java/com/xpeho/spring_boot_java_random_user/
    │   └── SpringBootJavaRandomUserApplicationTests.java
    └── resources/
        ├── application-test.properties               ← Test config (git-ignored)
        └── application-test.properties.template      ← Template to copy
.env                                                  ← Environment variables (git-ignored)
.env.template                                         ← Template to copy
docker-compose.yml                                    ← Local PostgreSQL

🗄️ Database

Schema

The user table is created automatically on startup via schema.sql:

Column Type Description
id SERIAL PK Auto-incremented identifier
gender VARCHAR(20) Gender
firstname VARCHAR(100) First name (name.first)
lastname VARCHAR(100) Last name (name.last)
civility VARCHAR(20) Title (name.title)
email VARCHAR(255) Email address
phone VARCHAR(50) Phone number
picture VARCHAR(500) Medium picture URL
nationality VARCHAR(10) Nationality

🌐 External API

This project consumes the public Random User Generator API:

✅ Todo

👤 Author

Project developed by XPEHO.