base-springboot-api-kotlin

Base Spring Boot API - Kotlin

A comprehensive Spring Boot API template built with Kotlin, following SOLID principles and best practices.

๐Ÿš€ Features

๐Ÿ—๏ธ Architecture

Layered Architecture Pattern

API Controllers โ†’ Facades โ†’ Repositories

Project Structure

src/main/kotlin/
โ”œโ”€โ”€ controller/     # REST endpoints (@RestController)
โ”œโ”€โ”€ facade/         # Business logic layer (@Service, @Transactional)
โ”œโ”€โ”€ service/        # External service integrations
โ”œโ”€โ”€ repository/     # Data access layer (@Repository)
โ”œโ”€โ”€ model/          # Entity classes (plain data classes)
โ”œโ”€โ”€ dto/            # Data Transfer Objects with OpenAPI schemas
โ”œโ”€โ”€ config/         # Configuration classes (@Configuration)
โ””โ”€โ”€ exception/      # Custom exceptions and handlers

๐Ÿ› ๏ธ Technology Stack

Component Technology Version
Language Kotlin 1.9.24
Framework Spring Boot 3.3.2
Build Tool Maven 3.9.x
Database Oracle Database 23ai
Connection Pool HikariCP Built-in
Migration Flyway 10.15.2
Documentation SpringDoc OpenAPI 2.6.0
Security Spring Security OAuth2 Built-in
Testing Kotest + MockK 5.9.1
Containers TestContainers 1.19.8

๐Ÿšฆ Getting Started

Prerequisites

1. Clone the Repository

git clone https://github.com/norvaldb/base-springboot-api-kotlin.git
cd base-springboot-api-kotlin

2. Start Oracle Database (Podman)

# Pull Oracle XE image
podman pull container-registry.oracle.com/database/express:latest

# Run Oracle XE container
podman run -d \
  --name oracle-xe \
  -p 1521:1521 \
  -e ORACLE_PWD=password123 \
  -e ORACLE_CHARACTERSET=AL32UTF8 \
  container-registry.oracle.com/database/express:latest

# Wait for database to be ready (2-3 minutes)
podman logs -f oracle-xe

3. Configure Environment Variables

export DB_USERNAME=dev_user
export DB_PASSWORD=dev_password
export DB_SCHEMA=DEV_SCHEMA
export JWT_ISSUER_URI=https://your-oauth2-provider.com

4. Run Database Migrations

# Create database schema and user (connect as system)
sqlplus system/password123@localhost:1521/XEPDB1

# In SQL*Plus:
CREATE USER dev_user IDENTIFIED BY dev_password;
GRANT DBA TO dev_user;
CREATE SCHEMA AUTHORIZATION dev_user;

# Run Flyway migrations
mvn flyway:migrate

5. Build and Run

# Build the application with automatic reports
mvn clean install

# Run tests only
mvn test

# Run integration tests
mvn verify

# Generate code coverage report (manual)
mvn jacoco:report

# Generate Allure report (manual)
mvn allure:report

# Start the application
mvn spring-boot:run

๐Ÿ“Š Code Coverage & Reporting

Automatic Report Generation

Both JaCoCo coverage and Allure test reports are automatically generated during mvn install:

# Single command generates everything
mvn clean install

Generated Reports:

Manual Report Generation

Manual Report Generation

For individual report generation (optional):

# Generate coverage report only
mvn jacoco:report

# Generate Allure report only
mvn allure:report

# Serve interactive Allure report
mvn allure:serve

Allure Test Reports

Allure Test Reports

# Serve interactive Allure report
mvn allure:serve

Coverage Reports Location:

Performance Optimizations:

Coverage Thresholds:

6. Access the Application

๐Ÿ“– API Documentation

The API is fully documented using OpenAPI 3.0 specification. Visit the Swagger UI at http://localhost:8080/swagger-ui.html for interactive documentation.

Authentication

The API uses OAuth2 JWT Bearer tokens for authentication:

Authorization: Bearer <your-jwt-token>

Example Endpoints

๐Ÿงช Testing

Unit Tests with Kotest

# Run unit tests
mvn test

Integration Tests with TestContainers

# Run integration tests (includes TestContainers)
mvn verify

Allure Report

This project is configured to produce Allure results for both unit and integration tests.

Notes:

Security Scanning with OWASP Dependency Check

# Run OWASP dependency vulnerability scan
mvn org.owasp:dependency-check-maven:check

# Generate report without failing build
mvn org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=11

Generated Reports:

Configuration:

Setting up NVD API Key:

  1. Get a free API key from NVD
  2. Local Development: Set environment variable export NVD_API_KEY=your-key-here
  3. GitHub Actions: Add NVD_API_KEY as a repository secret in Settings โ†’ Secrets and variables โ†’ Actions

Example Test Structure

class UserFacadeTest : FunSpec({
    
    val userRepository = mockk<UserRepository>()
    val userFacade = UserFacadeImpl(userRepository)
    
    test("should find user by id") {
        // Given
        val userId = 1L
        val user = User(id = userId, email = "test@example.com")
        every { userRepository.findById(userId) } returns user
        
        // When
        val result = userFacade.findById(userId)
        
        // Then
        result shouldNotBe null
        result?.id shouldBe userId
        result?.email shouldBe "test@example.com"
    }
})

๏ฟฝ GitHub Actions CI/CD

Automated Testing & Reporting

This project includes comprehensive GitHub Actions workflows for automated testing and reporting:

CI Pipeline Test Reports

Available Workflows

1. CI Pipeline (ci.yml)

Triggers: Push to main/develop, Pull Requests to main

Features:

2. Test Reports Only (test-reports.yml)

Triggers: Push to main/develop, Pull Requests to main

Features:

Accessing Reports

JaCoCo Coverage Reports:

Allure Test Reports:

Setting up GitHub Pages (Optional)

To enable automatic deployment of test reports to GitHub Pages:

  1. Go to Repository Settings โ†’ Pages
  2. Source: Deploy from a branch
  3. Branch: gh-pages
  4. Folder: / (root)

The CI pipeline will automatically deploy Allure reports with test history to your GitHub Pages site.

Coverage Requirements

The workflows enforce coverage thresholds:

Failed coverage checks will be reported in PR comments and workflow status.

๏ฟฝ๐Ÿ—„๏ธ Database

Oracle Database Setup

The application uses Oracle Database 23ai with the following configuration:

Flyway Migrations

Database migrations are located in src/main/resources/db/migration/:

db/migration/
โ”œโ”€โ”€ V1__Create_users_table.sql
โ”œโ”€โ”€ V2__Add_user_indexes.sql
โ””โ”€โ”€ V3__Create_audit_tables.sql

Example Migration

-- V1__Create_users_table.sql
CREATE TABLE users (
    user_id NUMBER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    email VARCHAR2(255) NOT NULL UNIQUE,
    status VARCHAR2(50) DEFAULT 'ACTIVE',
    created_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_status ON users(status);

๐Ÿ”ง Configuration

Application Profiles

Environment Variables

Variable Description Default
DB_USERNAME Database username dev_user
DB_PASSWORD Database password dev_password
DB_SCHEMA Database schema DEV_SCHEMA
JWT_ISSUER_URI OAuth2 JWT issuer https://your-oauth2-provider.com
CORS_ALLOWED_ORIGINS CORS allowed origins http://localhost:3000

๐Ÿ“‹ Development Guidelines

This project follows the comprehensive Copilot instructions located in .github/copilot-instructions.md. Key principles:

SOLID Principles

Code Standards

Security

๐Ÿณ Docker Support

Development with Podman

# Start Oracle Database
podman run -d \
  --name oracle-xe \
  -p 1521:1521 \
  -e ORACLE_PWD=password123 \
  container-registry.oracle.com/database/express:latest

Application Container (Future)

FROM openjdk:21-jdk-slim
COPY target/base-springboot-api-kotlin-*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

๐Ÿค Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Follow the coding standards in .github/copilot-instructions.md
  4. Add tests for new functionality
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

๐Ÿ“ License

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

๐Ÿ“ž Support

For questions and support:

Built with โค๏ธ using Kotlin and Spring Boot