Skip to content

README.md

Latest commit

 

History

History
217 lines (152 loc) · 7.57 KB

README.md

File metadata and controls

217 lines (152 loc) · 7.57 KB

🧪 RESTful API with Java and Spring Boot

Java CI with Maven Quality Gate Status Codacy Badge codecov CodeFactor License: MIT

A production-ready RESTful Web Service demonstrating clean architecture patterns with Spring Boot 4, comprehensive testing, and containerized deployment.

Table of Contents

About

A proof-of-concept RESTful Web Service built with Spring Boot 4 targeting JDK 25 (LTS). This project demonstrates best practices for building a layered, testable, and maintainable API implementing CRUD operations for a Books resource.

The service showcases:

  • Multi-layer architecture (Controllers → Services → Repositories)
  • In-memory H2 database with JPA/Hibernate
  • Spring Cache abstraction for performance optimization
  • Comprehensive test coverage with JUnit 5, Mockito, and AssertJ
  • OpenAPI 3.0 documentation with Swagger UI
  • Production-ready monitoring with Spring Boot Actuator
  • Containerized deployment with Docker

Features

  • ✅ RESTful API - Full CRUD operations for Books resource
  • ✅ Clean Architecture - Layered design with clear separation of concerns
  • ✅ Validation - Jakarta Bean Validation with custom constraints (ISBN, URL)
  • ✅ Caching - Spring Cache with @Cacheable, @CachePut, @CacheEvict
  • ✅ API Documentation - Interactive Swagger UI powered by SpringDoc OpenAPI
  • ✅ Health Monitoring - Spring Boot Actuator endpoints
  • ✅ Test Coverage - JaCoCo reports with Codecov/Codacy integration
  • ✅ Docker Support - Multi-stage builds with Eclipse Temurin Alpine images
  • ✅ CI/CD Ready - GitHub Actions with automated testing and container builds

Architecture

Simplified, conceptual project structure and main application flow

Figure: Simplified, conceptual project structure and main application flow. Not all dependencies are shown.

Layer Responsibilities:

  • Controller (Green) - HTTP request handling, DTO validation, OpenAPI annotations
  • Service (Yellow) - Business logic, caching, Entity-DTO mapping
  • Repository (Red) - Data access via Spring Data JPA

Prerequisites

Before you begin, ensure you have the following installed:

  • Java Development Kit (JDK) 25 - Download
    • Verify with: java -version
  • Maven 3.9+ (optional) - Project includes Maven wrapper (./mvnw)
  • Docker (optional) - For containerized deployment

macOS Users: Set JAVA_HOME if needed:

export JAVA_HOME=$(/usr/libexec/java_home -v 25)

Getting Started

Local Development

  1. Clone the repository

    git clone https://github.com/nanotaboada/java.samples.spring.boot.git
cd java.samples.spring.boot

  2. Build the project

    ./mvnw clean package

  3. Run the application

    ./mvnw spring-boot:run

  4. Verify it's running

    • API Server: http://localhost:9000
    • Health Check: http://localhost:9001/actuator/health
    • Swagger UI: http://localhost:9000/swagger/index.html

Docker Deployment

Quick Start:

docker compose up

Detached Mode:

docker compose up -d

Stop Containers:

docker compose down

Exposed Ports:

  • 9000 - Main API server
  • 9001 - Actuator management endpoints

API Reference

The Books API provides standard CRUD operations:

Method Endpoint Description Request Body Response
GET /books Retrieve all books - 200 OK with BookDTO[]
GET /books/{isbn} Retrieve book by ISBN - 200 OK with BookDTO or 404 Not Found
POST /books Create a new book BookDTO 201 Created with BookDTO
PUT /books/{isbn} Update existing book BookDTO 200 OK with BookDTO or 404 Not Found
DELETE /books/{isbn} Delete book by ISBN - 204 No Content or 404 Not Found

BookDTO Schema:

{
  "isbn": "978-0-596-52068-7",
  "title": "RESTful Web Services",
  "author": "Leonard Richardson, Sam Ruby",
  "published": "2007-05-08",
  "publisher": "O'Reilly Media",
  "pages": 448,
  "description": "An in-depth guide to building web services...",
  "website": "https://example.com"
}

For complete API documentation with request/response examples, visit the Swagger UI at:

http://localhost:9000/swagger/index.html

API Documentation

Testing

Run the full test suite with coverage:

./mvnw verify

View Coverage Report:

open target/site/jacoco/index.html

Test Structure:

  • Unit Tests - @WebMvcTest, @DataJpaTest for isolated layer testing (with @AutoConfigureCache for caching support)
  • Mocking - Mockito with @MockitoBean for dependency mocking
  • Assertions - AssertJ fluent assertions
  • Naming Convention - BDD style: given<Condition>_when<Action>_then<Expected>

Coverage Targets:

  • Controllers: 100%
  • Services: 100%
  • Repositories: Custom query methods (interfaces excluded by JaCoCo design)

Documentation

  • API Documentation: Swagger UI at http://localhost:9000/swagger/index.html
  • OpenAPI Spec: Available at http://localhost:9000/v3/api-docs
  • Actuator Endpoints: http://localhost:9001/actuator
  • Agent Onboarding: See .github/copilot-instructions.md for development guidelines

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

  • Code of Conduct
  • Development workflow
  • Commit message conventions
  • Pull request process

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This solution has been developed using Visual Studio Code.

All trademarks, registered trademarks, service marks, product names, company names, or logos mentioned on this repository are the property of their respective owners. All usage of such terms herein is for identification purposes only and constitutes neither an endorsement nor a recommendation of those items. Furthermore, the use of such terms is intended to be for educational and informational purposes only.