https://github.com/ksb0896/api-gateway-service
API gateway a central entry point for all microservices in the User-profile project
https://github.com/ksb0896/api-gateway-service
cloud-gateway java17 jwt-token openapi-spec spring-boot spring-security spring-webflux swagger-api swagger-ui
Last synced: about 2 months ago
JSON representation
API gateway a central entry point for all microservices in the User-profile project
- Host: GitHub
- URL: https://github.com/ksb0896/api-gateway-service
- Owner: ksb0896
- Created: 2025-10-14T16:13:44.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2026-03-18T14:42:56.000Z (4 months ago)
- Last Synced: 2026-03-19T05:00:30.245Z (4 months ago)
- Topics: cloud-gateway, java17, jwt-token, openapi-spec, spring-boot, spring-security, spring-webflux, swagger-api, swagger-ui
- Language: Java
- Homepage:
- Size: 344 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🚀 API Gateway for User Profile Service
## Overview
A **Spring Cloud Gateway** service that acts as the central entry point for all microservices in the system. It provides JWT authentication, request routing, API aggregation, and Swagger/OpenAPI documentation.
---
## 📋 Quick Start
- **Port**: 8080
- **Type**: Spring Cloud Gateway (Reactive/WebFlux)
- **Java Version**: 17
- **Spring Boot Version**: 3.5.6
- **Spring Cloud Version**: 2025.0.0
---
## 🏗️ Architecture
### Services Managed by Gateway
| Service | Port | Endpoint | Purpose |
|---------|------|----------|---------|
| **API Gateway** | 8080 | `http://localhost:8080` | Main entry point, routing, authentication |
| **User Profile Service** | 8081 | `http://localhost:8081` | User management, profiles |
| **Profile Photo Service** | 8082 | `http://localhost:8082` | Photo upload and management |
| **Auth Service** | 8083 | `http://localhost:8083` | Authentication, JWT token generation |
---
## 🔐 Authentication
### JWT Token-Based Authentication
All requests to protected endpoints require a Bearer token:
```bash
curl -X GET http://localhost:8080/v1/banks/100/users \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```
**Token Generation:**
1. Call Auth Service: `POST http://localhost:8083/auth/login`
2. Provide credentials: `{"username": "user", "password": "pass"}`
3. Receive JWT token in response
4. Use token in `Authorization: Bearer ` header
### JWT Configuration
- **Algorithm**: HS256 (HMAC with SHA-256)
- **Secret Key**: `MySecureKeyForMicroservicesMustBeVeryLongAndSafe`
- **Expiration**: 1 hour (3600000 ms)
---
## 🛣️ API Routes
### Route 1: User Profile Service
**Path**: `/v1/banks/*/users/**`
**Target**: `http://localhost:8081`
**Filters**: Authentication, RewritePath
**Example**: `GET /v1/banks/103/users/7025868222864118611`
### Route 2: Profile Photo Service
**Path**: `/v1/banks/*/users/*/photo/**`
**Target**: `http://localhost:8082`
**Filters**: Authentication, CircuitBreaker, RewritePath
**Example**: `POST /v1/banks/103/users/7025868222864118611/photo`
### Route 3: Auth Service
**Path**: `/auth/**`
**Target**: `http://localhost:8083`
**Filters**: StripPrefix
**Example**: `POST /auth/login`, `GET /auth/validate`
---
## 📚 API Documentation
### Swagger UI
- **Main Page**: http://localhost:8080/swagger-ui/index.html
- **OpenAPI Spec**: http://localhost:8080/v3/api-docs
### Service Documentation
| Service | Swagger URL | OpenAPI Spec |
|---------|-------------|--------------|
| Gateway | `http://localhost:8080/swagger-ui.html` | `http://localhost:8080/v3/api-docs` |
| User Service | `http://localhost:8081/swagger-ui.html` | `http://localhost:8081/v3/api-docs` |
| Auth Service | `http://localhost:8083/swagger-ui.html` | `http://localhost:8083/v3/api-docs` |
---
## 🔧 Technologies & Dependencies
### Core Framework
- Spring Boot 3.5.6
- Spring Cloud Gateway 2025.0.0
- Spring WebFlux (Reactive)
- Spring Security
### API Documentation
- springdoc-openapi-starter-webflux-ui 2.5.0
- Swagger UI
- OpenAPI 3.0
### Security & JWT
- JJWT 0.11.5
- Spring Security
- JWT Token-based authentication
### Resilience
- Resilience4j 2.x
- Circuit Breaker
- Retry Logic
- Timeout Management
### Monitoring & Health
- Spring Boot Actuator
- Health Endpoints
---
## 🚀 Running the Application
### Option 1: Using Batch Script (Recommended)
```powershell
# Windows - From project root
.\batch\START_GATEWAY_DEBUG.cmd
```
### Option 2: Manual Start
```powershell
# Kill any existing Java processes
Stop-Process -Name java -Force -ErrorAction SilentlyContinue
# Wait 3 seconds
Start-Sleep -Seconds 3
# Start the gateway
cd C:\ksb096-B\prjcts\sts\user-service\api-gateway-service
java -jar target\api_gateway-0.0.1-SNAPSHOT.jar
```
### Option 3: Using Maven
```bash
mvn clean package -DskipTests
java -jar target/api_gateway-0.0.1-SNAPSHOT.jar
```
---
## 📝 Configuration Files
### Main Configuration
**File**: `src/main/resources/application.properties`
Key settings:
- Server port: 8080
- Gateway routes: 5 routes configured
- JWT configuration
- Logging levels
- Resilience4j settings
- Swagger/OpenAPI configuration
---
## 🔄 Request Flow
```
Client Request
↓
API Gateway (8080)
├─ Spring Security: Allow all routes
├─ Path Predicate: Match route pattern
├─ Authentication Filter: Validate JWT token
│ ├─ Extract token from Authorization header
│ ├─ Validate JWT signature
│ ├─ Check token expiration
│ └─ Extract username
├─ RewritePath Filter: Transform path if needed
├─ CircuitBreaker: Check service health
└─ Forward to Backend Service
↓
Backend Service (8081/8082/8083)
├─ Process request
├─ Return response
└─ Send to Gateway
↓
API Gateway (8080)
└─ Return response to Client
↓
Client Response
```
---
## 🧪 Testing
### Test with cURL
```bash
# 1. Login to get token
curl -X POST http://localhost:8083/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"DecUserOne","password":"password123"}'
# 2. Use token to call protected endpoint
curl -X GET http://localhost:8080/v1/banks/103/users/7025868222864118611 \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
```
### Test with Swagger UI
1. Open: http://localhost:8080/swagger-ui/index.html
2. Select service from dropdown
3. Click "Try it out" on any endpoint
4. Add Bearer token if required
5. Click "Execute"
---
## 🐛 Issues Fixed
### ✅ Issue 1: 401 Unauthorized Error
- **Cause**: JWT API incompatibility between token generation and validation
- **Fix**: Updated to modern JJWT 0.11.x+ API
- **Status**: RESOLVED
### ✅ Issue 2: Spring Security Blocking Requests
- **Cause**: `.authenticated()` requirement blocking all requests
- **Fix**: Changed to `.permitAll()` to let JWT filter handle auth
- **Status**: RESOLVED
### ✅ Issue 3: 404 Route Not Matching
- **Cause**: Invalid path pattern for Spring Cloud Gateway 4.3.0
- **Fix**: Updated to valid wildcard patterns
- **Status**: RESOLVED
### ✅ Issue 4: 500 Backend Service Error
- **Cause**: Path rewriting losing bank ID
- **Fix**: Preserved full path with `StripPrefix=0`
- **Status**: RESOLVED
### ✅ Issue 5: Swagger 404 Error
- **Cause**: Gateway routes pointing to non-existent paths
- **Fix**: Updated URIs to point to service base URLs with correct RewritePath
- **Status**: RESOLVED
---
## 📚 Documentation
Comprehensive documentation available in `/documents/` folder:
| Document | Purpose |
|----------|---------|
| SWAGGER_SETUP_SUMMARY.md | Swagger setup guide |
| DEBUGGING_GUIDE.md | Troubleshooting reference |
| FIX_SUMMARY.md | Technical details of fixes |
| COMPLETE_TESTING_CHECKLIST.md | Testing procedures |
| QUICK_REFERENCE.txt | Command cheat sheet |
---
## 🛠️ Scripts
Available in `/batch/` folder:
| Script | Purpose |
|--------|---------|
| START_GATEWAY_DEBUG.cmd | Start with full console output |
| RESTART_GATEWAY.bat | Restart with clean process |
| test_gateway.ps1 | Automated testing script |
---
## 📊 Logging
### Debug Logging Enabled
```properties
logging.level.org.springframework.cloud.gateway=DEBUG
logging.level.reactor.netty.http.client=DEBUG
logging.level.com.ksb.micro.api_gateway.filter=DEBUG
logging.level.com.ksb.micro.api_gateway.util=DEBUG
```
### Log Output Examples
```
>>> [GATEWAY FILTER] Processing request to: /v1/banks/103/users
>>> [GATEWAY FILTER] Authorization header present, length: 350
>>> [JWT] ✓ Token validation SUCCESSFUL
>>> [GATEWAY FILTER] ✓ TOKEN VALID - Username: DecUserOne
```
---
## 🔗 Related Services
### User Profile Service (8081)
- Manages user profiles and data
- Requires JWT authentication
- Documentation: http://localhost:8081/swagger-ui.html
### Auth Service (8083)
- Handles user authentication
- Generates JWT tokens
- No authentication required
- Documentation: http://localhost:8083/swagger-ui.html
### Profile Photo Service (8082)
- Manages photo uploads
- Requires JWT authentication
- Documentation: http://localhost:8082/swagger-ui.html
---
## ✅ Deployment Checklist
Before deploying to production:
- [ ] JWT secret key changed to secure value
- [ ] All services configured and running
- [ ] Swagger documentation complete
- [ ] API endpoints tested with valid tokens
- [ ] CORS configured if needed
- [ ] Logging levels appropriate
- [ ] Circuit breaker thresholds set correctly
- [ ] Health endpoints working
- [ ] Error handling tested
- [ ] Rate limiting configured (if needed)
---
## 📞 Support
For issues or questions:
1. Check: `/documents/DEBUGGING_GUIDE.md` for troubleshooting
2. Review: `/documents/QUICK_REFERENCE.txt` for common commands
3. Test: Use Swagger UI at http://localhost:8080/swagger-ui/index.html
---
## 📝 Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-12-06 | Initial setup with JWT auth, routes, and Swagger |
---
## 🎯 Key Features
✅ **JWT Authentication** - Secure token-based authentication
✅ **Route Aggregation** - Central gateway for all services
✅ **API Documentation** - Swagger/OpenAPI with multiple services
✅ **Request Routing** - Intelligent path matching and forwarding
✅ **Error Handling** - Comprehensive error messages and logging
✅ **Circuit Breaker** - Resilience4j for fault tolerance
✅ **CORS Support** - Cross-origin request handling
✅ **Health Checks** - Service health monitoring
---
**Last Updated**: December 6, 2025
**Status**: ✅ Production Ready
**Maintainer**: ksb0896