Skip to content

Commit cdc3194

Browse files
nanotaboadananotaboada
authored
Merge pull request #230 from nanotaboada/feature/enhance-README
docs: modernize README with comprehensive documentation
2 parents 0246f1c + 1d87e21 commit cdc3194

File tree

1 file changed

+179
-20
lines changed

1 file changed

+179
-20
lines changed

‎README.md‎

Lines changed: 179 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,218 @@
1-
# 🧪 RESTful Web Service with Spring Boot
2-
3-
## Status
1+
# 🧪 RESTful API with Java and Spring Boot
42

53
[![Java CI with Maven](https://github.com/nanotaboada/java.samples.spring.boot/actions/workflows/maven.yml/badge.svg)](https://github.com/nanotaboada/java.samples.spring.boot/actions/workflows/maven.yml)
64
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nanotaboada_java.samples.spring.boot&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=nanotaboada_java.samples.spring.boot)
75
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ea6918db332642089ef420822267931b)](https://app.codacy.com/gh/nanotaboada/java.samples.spring.boot/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
86
[![codecov](https://codecov.io/gh/nanotaboada/java.samples.spring.boot/branch/master/graph/badge.svg?token=D3FMNG0WOI)](https://codecov.io/gh/nanotaboada/java.samples.spring.boot)
97
[![CodeFactor](https://www.codefactor.io/repository/github/nanotaboada/java.samples.spring.boot/badge)](https://www.codefactor.io/repository/github/nanotaboada/java.samples.spring.boot)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9+
10+
> A production-ready RESTful Web Service demonstrating clean architecture patterns with Spring Boot 3, comprehensive testing, and containerized deployment.
11+
12+
## Table of Contents
13+
14+
- [About](#about)
15+
- [Features](#features)
16+
- [Architecture](#architecture)
17+
- [Prerequisites](#prerequisites)
18+
- [Getting Started](#getting-started)
19+
- [Local Development](#local-development)
20+
- [Docker Deployment](#docker-deployment)
21+
- [API Reference](#api-reference)
22+
- [Testing](#testing)
23+
- [Documentation](#documentation)
24+
- [Contributing](#contributing)
25+
- [License](#license)
1026

1127
## About
1228

13-
Proof of Concept for a RESTful Web Service made with [Spring Boot 3](https://spring.io/blog/2024/02/22/spring-boot-3-2-3-available-now) targeting [JDK 21](https://openjdk.org/projects/jdk/21/)
29+
A proof-of-concept RESTful Web Service built with **Spring Boot 3** targeting **JDK 21 (LTS)**. This project demonstrates best practices for building a layered, testable, and maintainable API implementing CRUD operations for a Books resource.
30+
31+
The service showcases:
32+
33+
- Multi-layer architecture (Controllers → Services → Repositories)
34+
- In-memory H2 database with JPA/Hibernate
35+
- Spring Cache abstraction for performance optimization
36+
- Comprehensive test coverage with JUnit 5, Mockito, and AssertJ
37+
- OpenAPI 3.0 documentation with Swagger UI
38+
- Production-ready monitoring with Spring Boot Actuator
39+
- Containerized deployment with Docker
40+
41+
## Features
1442

15-
## Structure
43+
- ✅ **RESTful API** - Full CRUD operations for Books resource
44+
- ✅ **Clean Architecture** - Layered design with clear separation of concerns
45+
- ✅ **Validation** - Jakarta Bean Validation with custom constraints (ISBN, URL)
46+
- ✅ **Caching** - Spring Cache with `@Cacheable`, `@CachePut`, `@CacheEvict`
47+
- ✅ **API Documentation** - Interactive Swagger UI powered by SpringDoc OpenAPI
48+
- ✅ **Health Monitoring** - Spring Boot Actuator endpoints
49+
- ✅ **Test Coverage** - JaCoCo reports with Codecov/Codacy integration
50+
- ✅ **Docker Support** - Multi-stage builds with Eclipse Temurin Alpine images
51+
- ✅ **CI/CD Ready** - GitHub Actions and Azure Pipelines configurations
52+
53+
## Architecture
1654

1755
![Simplified, conceptual project structure and main application flow](assets/images/structure.svg)
1856

1957
_Figure: Simplified, conceptual project structure and main application flow. Not all dependencies are shown._
2058

21-
## Documentation
59+
**Layer Responsibilities:**
60+
61+
- **Controller** (Green) - HTTP request handling, DTO validation, OpenAPI annotations
62+
- **Service** (Yellow) - Business logic, caching, Entity-DTO mapping
63+
- **Repository** (Red) - Data access via Spring Data JPA
64+
65+
## Prerequisites
66+
67+
Before you begin, ensure you have the following installed:
68+
69+
- **Java Development Kit (JDK) 21** - [Download](https://adoptium.net/temurin/releases/?version=21)
70+
- ⚠️ **Critical**: JDK 21 is required. Newer versions (22+) cause Mockito/ByteBuddy compatibility issues.
71+
- Verify with: `java -version`
72+
- **Maven 3.9+** (optional) - Project includes Maven wrapper (`./mvnw`)
73+
- **Docker** (optional) - For containerized deployment
74+
75+
**macOS Users**: Set `JAVA_HOME` if needed:
2276

23-
```console
24-
http://localhost:9000/swagger/index.html
77+
```bash
78+
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
2579
```
2680

27-
![API Documentation](assets/images/swagger.png)
81+
## Getting Started
82+
83+
### Local Development
84+
85+
1. **Clone the repository**
86+
87+
```bash
88+
git clone https://github.com/nanotaboada/java.samples.spring.boot.git
89+
cd java.samples.spring.boot
90+
```
91+
92+
2. **Build the project**
93+
94+
```bash
95+
./mvnw clean package
96+
```
2897

29-
## Container
98+
3. **Run the application**
3099

31-
### Docker Compose
100+
```bash
101+
./mvnw spring-boot:run
102+
```
32103

33-
This setup uses [Docker Compose](https://docs.docker.com/compose/) to build and run the app
104+
4. **Verify it's running**
105+
- API Server: `http://localhost:9000`
106+
- Health Check: `http://localhost:9001/actuator/health`
107+
- Swagger UI: `http://localhost:9000/swagger/index.html`
34108

35-
#### Build the image
109+
### Docker Deployment
110+
111+
**Quick Start:**
36112

37113
```bash
38-
docker compose build
114+
docker compose up
39115
```
40116

41-
#### Start the app
117+
**Detached Mode:**
42118

43119
```bash
44-
docker compose up
120+
docker compose up -d
45121
```
46122

47-
#### Stop the app
123+
**Stop Containers:**
48124

49125
```bash
50126
docker compose down
51127
```
52128

53-
## Credits
129+
**Exposed Ports:**
130+
131+
- `9000` - Main API server
132+
- `9001` - Actuator management endpoints
133+
134+
## API Reference
135+
136+
The Books API provides standard CRUD operations:
137+
138+
| Method | Endpoint | Description | Request Body | Response |
139+
|--------|----------|-------------|--------------|----------|
140+
| `GET` | `/books` | Retrieve all books | - | `200 OK` with `BookDTO[]` |
141+
| `GET` | `/books/{isbn}` | Retrieve book by ISBN | - | `200 OK` with `BookDTO` or `404 Not Found` |
142+
| `POST` | `/books` | Create a new book | `BookDTO` | `201 Created` with `BookDTO` |
143+
| `PUT` | `/books/{isbn}` | Update existing book | `BookDTO` | `200 OK` with `BookDTO` or `404 Not Found` |
144+
| `DELETE` | `/books/{isbn}` | Delete book by ISBN | - | `204 No Content` or `404 Not Found` |
145+
146+
**BookDTO Schema:**
147+
148+
```json
149+
{
150+
"isbn": "978-0-596-52068-7",
151+
"title": "RESTful Web Services",
152+
"author": "Leonard Richardson, Sam Ruby",
153+
"published": "2007-05-08",
154+
"publisher": "O'Reilly Media",
155+
"pages": 448,
156+
"description": "An in-depth guide to building web services...",
157+
"website": "https://example.com"
158+
}
159+
```
160+
161+
For complete API documentation with request/response examples, visit the **Swagger UI** at:
162+
163+
`http://localhost:9000/swagger/index.html`
164+
165+
![API Documentation](assets/images/swagger.png)
166+
167+
## Testing
168+
169+
Run the full test suite with coverage:
170+
171+
```bash
172+
./mvnw verify
173+
```
174+
175+
**View Coverage Report:**
176+
177+
```bash
178+
open target/site/jacoco/index.html
179+
```
180+
181+
**Test Structure:**
182+
183+
- **Unit Tests** - `@WebMvcTest`, `@DataJpaTest` for isolated layer testing
184+
- **Mocking** - Mockito for dependency mocking
185+
- **Assertions** - AssertJ fluent assertions
186+
- **Naming Convention** - BDD style: `given<Condition>_when<Action>_then<Expected>`
187+
188+
**Coverage Targets:**
189+
190+
- Controllers: 100%
191+
- Services: 100%
192+
- Repositories: Custom query methods (interfaces excluded by JaCoCo design)
193+
194+
## Documentation
195+
196+
- **API Documentation**: Swagger UI at `http://localhost:9000/swagger/index.html`
197+
- **OpenAPI Spec**: Available at `http://localhost:9000/v3/api-docs`
198+
- **Actuator Endpoints**: `http://localhost:9001/actuator`
199+
- **Agent Onboarding**: See `.github/copilot-instructions.md` for development guidelines
200+
201+
## Contributing
202+
203+
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
204+
205+
- Code of Conduct
206+
- Development workflow
207+
- Commit message conventions
208+
- Pull request process
209+
210+
## License
211+
212+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
54213

55-
The solution has been coded using [Visual Studio Code](https://code.visualstudio.com/) with the [Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
214+
## Acknowledgments
56215

57-
## Terms
216+
This solution has been developed using [Visual Studio Code](https://code.visualstudio.com/).
58217

59218
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.

0 commit comments

Comments
 (0)