🚀 kotlin-api

A reactive REST API built with Kotlin, Spring Boot WebFlux, and MongoDB — featuring JWT authentication, role-based access control, and OpenAPI documentation.

---

📋 Table of Contents

• Features
• Tech Stack
• Getting Started
  • Prerequisites
  • Configuration
  • Run Locally
  • Run with Docker
• API Reference
• Project Structure
• Documentation
• Development

---

✨ Features

• ⚡ Reactive — fully non-blocking with Spring WebFlux & Kotlin coroutines
• 🔐 JWT authentication — AES-256-GCM encrypted tokens (JWE), access + refresh token flow
• 🛡️ Role-based access control — ROLE_ADMIN and standard user roles
• 🔄 Token lifecycle management — refresh, revocation, and session tracking
• 📖 OpenAPI / Swagger UI — auto-generated, browsable API docs
• 🐳 Docker-ready — multi-stage distroless image for minimal attack surface
• ✅ Code quality — enforced with ktlint

---

🛠 Tech Stack

Layer	Technology
Language	Kotlin 2.4
Framework	Spring Boot 4.1 (WebFlux)
Runtime	Java 21
Database	MongoDB 8 (reactive)
Security	Spring Security + JJWT (JWE)
Docs	SpringDoc OpenAPI 3
Testing	JUnit 5, MockK, embedded MongoDB
Linting	ktlint 1.8

---

🏁 Getting Started

Prerequisites

• Java 21+
• MongoDB 8 (or Docker)

Configuration

cp .env.example .env

Edit .env and set the required values:

Variable	Description	Default
MONGODB_URI	MongoDB connection string	mongodb://localhost:27017/kotlin-api
JWT_ENCRYPTION_SECRET	Base64-encoded 32-byte AES secret (required)	—

Generate a secret:

openssl rand -base64 32 | tr -d '\n'

Run Locally

./gradlew bootRun

The API starts on http://localhost:8080.

Seed Users

On startup, two users are automatically created if they don't already exist:

Email	Password	Role
user@example.com	user12345	ROLE_USER
admin@example.com	admin12345	ROLE_ADMIN

Use these credentials with POST /v1/auth/login to get started quickly.

Run with Docker

docker compose up --build

This spins up both the API and MongoDB with a persistent volume.

---

📡 API Reference

All routes are versioned under /v1. Interactive docs available at http://localhost:8080/swagger-ui.html.

🔓 Auth

Method	Endpoint	Auth	Description
POST	/v1/auth/login	—	Login, returns access + refresh tokens
POST	/v1/auth/refresh	—	Exchange refresh token for a new access token
POST	/v1/auth/logout	Bearer	Revoke all refresh tokens for the current user

👤 Users

Method	Endpoint	Auth	Description
GET	/v1/users/me	Bearer	Get current user info and active sessions
GET	/v1/users	Admin	List all users

🔧 Admin

Method	Endpoint	Auth	Description
POST	/v1/admin/users	Admin	Create a new user

💚 Health

Method	Endpoint	Description
GET	/v1/health	API and MongoDB health status

---

📁 Project Structure

src/main/kotlin/io/visus/demos/kotlinapi/
├── api/                  # Contracts (request/response DTOs), mappers, versioning
├── config/               # Spring configuration (security, JWT, OpenAPI, MongoDB)
├── controller/           # HTTP layer (Auth, Admin, Users, Health)
├── domain/
│   ├── model/            # Domain models
│   ├── service/          # Business logic interfaces + implementations
│   └── exception/        # Custom exceptions + global error handler
├── infrastructure/
│   ├── security/         # JWT filter, token provider, auth handlers
│   └── user/             # Repository interfaces (MongoDB)
└── seed/                 # Data seeder (dev only)

---

📚 Documentation

• Authentication & Security — JWE tokens, refresh rotation, theft detection, RBAC, and configuration

---

🧑‍💻 Development

# Run tests
./gradlew test

# Lint
./gradlew ktlintCheck

# Auto-fix lint issues
./gradlew ktlintFormat

# Check for dependency updates
./gradlew dependencyUpdates