184 lines
5.0 KiB
Markdown
184 lines
5.0 KiB
Markdown
# 🚀 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](#-features)
|
|
- [Tech Stack](#-tech-stack)
|
|
- [Getting Started](#-getting-started)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Configuration](#configuration)
|
|
- [Run Locally](#run-locally)
|
|
- [Run with Docker](#run-with-docker)
|
|
- [API Reference](#-api-reference)
|
|
- [Project Structure](#-project-structure)
|
|
- [Documentation](#-documentation)
|
|
- [Development](#-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
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
openssl rand -base64 32 | tr -d '\n'
|
|
```
|
|
|
|
### Run Locally
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
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](docs/authentication-and-security.md) — JWE tokens, refresh rotation, theft detection, RBAC, and configuration
|
|
|
|
---
|
|
|
|
## 🧑💻 Development
|
|
|
|
```bash
|
|
# Run tests
|
|
./gradlew test
|
|
|
|
# Lint
|
|
./gradlew ktlintCheck
|
|
|
|
# Auto-fix lint issues
|
|
./gradlew ktlintFormat
|
|
|
|
# Check for dependency updates
|
|
./gradlew dependencyUpdates
|
|
```
|