Identity Service API

DashboardUser Guide

Identity Service documentation

User Guide

Practical guidance for running, testing, inspecting, and maintaining the Identity Service locally and through its GitHub Actions delivery pipeline.

Project overview

Identity Service API is a compact Java 21 and Spring Boot 4 backend for user identity management. It demonstrates API versioning, password hashing, soft deletion, database migrations, consistent HTTP errors, real PostgreSQL integration tests, containerized startup, and automated documentation publication.

The project is intentionally scoped as one service. It does not introduce authentication tokens, distributed messaging, Kubernetes, or a browser application because those concerns are outside the current OpenAPI contract.

Runtime

Java 21, Spring Boot 4, Spring MVC, Spring Data JPA, and PostgreSQL 16.

Contract and mapping

OpenAPI Generator produces HTTP models and interfaces; MapStruct maps them to the domain.

Database lifecycle

Flyway migrations create and evolve the schema before Hibernate validates it.

Quality and delivery

JUnit, MockMvc, Testcontainers, JaCoCo, Docker Compose, and GitHub Actions form the validation path.

Architecture summary

  1. OpenAPI contract: identity-api.yaml defines the public API.
  2. Generated API layer: Maven generates Spring MVC interfaces and API models.
  3. Controllers: thin adapters implement the generated interfaces.
  4. Services: application logic owns validation, hashing, updates, and soft deletes.
  5. Domain and mapping: internal entities remain separate from generated API models.
  6. Repositories: Spring Data JPA persists the domain model in PostgreSQL.

API-first rule: change the YAML contract before changing public HTTP behavior, then regenerate through Maven and update implementation and tests.

Guide map

Getting started

Prerequisites, cloning, local database startup, application launch, and first checks.

Docker usage

Compose runtime, health checks, environment variables, shutdown, and cleanup.

API documentation

Source contract, generated docs, local Swagger UI, versioning, Postman, and generated code.

Testing

Unit, web-layer, repository, and Testcontainers integration verification.

Coverage

JaCoCo generation, local and published reports, exclusions, and interpretation.

Useful links