Identity Service API

Java 21 / Spring Boot 4 / PostgreSQL

Production-style identity backend with contract-first APIs.

A compact backend portfolio project focused on OpenAPI-driven Spring MVC contracts, layered domain logic, Flyway migrations, Docker Compose, Testcontainers integration tests, Maven reporting, and GitHub Actions delivery.

User Guide OpenAPI Docs GitHub Repository Coverage Report Maven Site

Architecture

Layered backend boundaries

The API contract is generated from OpenAPI, while domain and persistence logic stay in handwritten Spring components.

Client/API Consumer
OpenAPI Contractidentity-api.yaml
Controller Layergenerated interfaces implemented by Spring MVC adapters
Service Layerbusiness rules, password hashing, soft deletes
Domain LayerUser aggregate and lifecycle state
Repository LayerSpring Data JPA
PostgreSQLruntime database
MapStructmaps generated API models to internal domain objects
Flywayapplies schema migrations before JPA validation
Testcontainersruns integration tests against PostgreSQL
Docker Composestarts app and database with readiness checks
GitHub Actionsruns Maven verification, Docker validation, coverage and Pages deployment

Capabilities

What the project demonstrates

OpenAPI-first contract

The YAML contract drives generated Spring MVC APIs and static API docs.

Generated interfaces/models

OpenAPI and MapStruct outputs are produced during Maven builds.

v1/v2 APIs

Versioned endpoints show backward-compatible API evolution.

MapStruct

Compile-time DTO/domain mapping with strict unmapped-property checks.

Flyway

Database schema changes are represented as migrations.

RFC7807 ProblemDetail

Validation, conflicts, and missing resources return consistent errors.

Testcontainers

Integration tests use real PostgreSQL containers.

Docker Compose

PostgreSQL and the application start together with DB readiness checks.

GitHub Actions CI

Verification, Docker validation, reporting, and Pages deployment are automated.

JaCoCo coverage

HTML and XML coverage reports are generated during Maven verification.

API versioning

Compact v1, expanded v2

Version 1 exposes the minimal user lifecycle. Version 2 adds profile fields and partial updates while preserving the original contract.

v1

POST /api/v1/users

GET /api/v1/users/{id}

DELETE /api/v1/users/{id}

v2

POST /api/v2/users

GET /api/v2/users/{id}

PATCH /api/v2/users/{id}

Testing and CI

Verification-first pipeline

The main Maven gate is mvn clean verify. It runs unit tests, web-layer tests, Testcontainers integration tests, packaging, and JaCoCo report generation.

Service-layer behavior

Repository constraints against PostgreSQL

Versioned create, read, update, and soft-delete flows

Error and validation scenarios

Docker image and Compose validation

Docker

Validated local runtime

docker compose up --build starts PostgreSQL and the Spring Boot service. The application receives database credentials through DB_USERNAME and DB_PASSWORD, while Compose waits for PostgreSQL readiness. 

docker compose up --build

Coverage

JaCoCo reports published with the dashboard

Coverage is generated by Maven during mvn clean verify. CI publishes the HTML report beside this dashboard, and the XML report remains available in the build output. Generated OpenAPI and MapStruct implementation classes are excluded from coverage.

Open Coverage Report