be-service-qris/README.md

API Service

A comprehensive Go-based REST API service built with Gin framework, featuring PostgreSQL database integration, JWT authentication, Swagger documentation, WebSocket support, and containerized deployment.

🚀 Features

• RESTful API with Gin framework
• PostgreSQL database integration with GORM
• JWT Authentication with Keycloak integration
• Swagger/OpenAPI documentation
• WebSocket real-time communication support
• Docker containerization
• Graceful shutdown handling
• CORS support
• Error handling middleware
• Live reload with Air for development
• Comprehensive testing with integration tests

🏗️ Architecture

api-service/
├── cmd/api/                 # Application entry point
├── internal/
│   ├── config/             # Configuration management
│   ├── database/           # Database connection and models
│   ├── handlers/           # HTTP request handlers
│   ├── middleware/         # HTTP middleware
│   ├── models/             # Data models
│   ├── routes/             # Route definitions
│   └── server/             # HTTP server setup
├── docker-compose.yml      # Docker services configuration
├── Dockerfile             # Container image definition
├── Makefile               # Build automation
└── go.mod                 # Go module dependencies

🛠️ Technology Stack

• Language: Go 1.24.4
• Web Framework: Gin 1.10.1
• Database: PostgreSQL with GORM
• Authentication: JWT with Keycloak
• Documentation: Swagger/OpenAPI 3.0
• WebSocket: gorilla/websocket
• Testing: Testcontainers for integration tests
• Containerization: Docker & Docker Compose
• Hot Reload: Air for development

📋 Prerequisites

• Go 1.24.4 or higher
• PostgreSQL 12 or higher
• Docker & Docker Compose (optional)
• Keycloak server (for authentication)

🔧 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd api-service

2. Environment Configuration

Create a .env file in the project root:

# Server Configuration
PORT=8080
GIN_MODE=debug

# Database Configuration
BLUEPRINT_DB_HOST=localhost
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_USERNAME=postgres
BLUEPRINT_DB_PASSWORD=postgres
BLUEPRINT_DB_DATABASE=api_service
BLUEPRINT_DB_SCHEMA=public

# Keycloak Configuration
KEYCLOAK_ISSUER=https://keycloak.example.com/auth/realms/yourrealm
KEYCLOAK_AUDIENCE=your-client-id
KEYCLOAK_JWKS_URL=https://keycloak.example.com/auth/realms/yourrealm/protocol/openid-connect/certs
KEYCLOAK_ENABLED=true

3. Install Dependencies

go mod download

4. Database Setup

Option A: Using Docker Compose (Recommended)

make docker-run

Option B: Manual PostgreSQL Setup

# Create database
createdb api_service

# Run migrations (if any)
# go run cmd/migrate/main.go

5. Run the Application

Development Mode (with hot reload)

make watch

Production Mode

make build
./main.exe

🌐 API Endpoints

Base URL

http://localhost:8080/api/v1

Health Check

• GET /api/v1/health - Health check endpoint
• GET /api/v1/ - Hello world endpoint

Example Endpoints

• GET /api/v1/example - Get example data
• POST /api/v1/example - Create example data

WebSocket

• GET /api/v1/websocket - WebSocket endpoint
• GET /api/v1/webservice - Web service endpoint

Swagger Documentation

• GET /swagger/index.html - Interactive API documentation

🔐 Authentication

The API uses JWT tokens for authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

🧪 Testing

Unit Tests

make test

Integration Tests

make itest

Run All Tests

make all

🐳 Docker Deployment

Build and Run with Docker Compose

# Development
make docker-run

# Production
docker-compose -f docker-compose.yml up --build -d

Docker Commands

# Build image
docker build -t api-service .

# Run container
docker run -p 8080:8080 --env-file .env api-service

📊 Monitoring & Logging

• Health Check: /api/v1/health
• Metrics: Available through middleware
• Logging: Structured logging with Gin

🔄 Development Workflow

1. Feature Development

   git checkout -b feature/your-feature
   make watch  # Start development server with hot reload
   

2. Testing

   make test
   make itest
   

3. Code Quality

   go fmt ./...
   go vet ./...
   

4. Build & Run

   make build
   make run
   

📝 API Documentation

After starting the server, visit:

• Swagger UI: http://localhost:8080/swagger/index.html
• OpenAPI JSON: http://localhost:8080/swagger/doc.json

CLI Command to Generate Swagger Documentation

Generate Swagger documentation using the following command:

swag init -g cmd/api/main.go --output docs

This command will:

• Scan your Go source code for Swagger annotations
• Generate OpenAPI 3.0 specification files
• Create/update the documentation in docs/ directory
• Include all API endpoints, models, and authentication details

Make sure to run this command whenever you add new endpoints or modify existing API documentation.

🚀 Production Deployment

Environment Variables

Set the following for production:

GIN_MODE=release
PORT=8080

Docker Production

docker build -t api-service:prod .
docker run -d -p 8080:8080 --env-file .env api-service:prod

Health Check

curl -f http://localhost:8080/api/v1/health || exit 1

🔧 Configuration

Server Configuration

Variable	Default	Description
PORT	8080	Server port
GIN_MODE	debug	Gin mode (debug/release/test)

Database Configuration

Variable	Default	Description
BLUEPRINT_DB_HOST	localhost	Database host
BLUEPRINT_DB_PORT	5432	Database port
BLUEPRINT_DB_USERNAME	postgres	Database username
BLUEPRINT_DB_PASSWORD	postgres	Database password
BLUEPRINT_DB_DATABASE	api_service	Database name
BLUEPRINT_DB_SCHEMA	public	Database schema

Keycloak Configuration

Variable	Default	Description
KEYCLOAK_ISSUER	-	Keycloak issuer URL
KEYCLOAK_AUDIENCE	-	Keycloak audience/client ID
KEYCLOAK_JWKS_URL	-	Keycloak JWKS URL
KEYCLOAK_ENABLED	true	Enable/disable Keycloak auth

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🆘 Support

For support, email support@example.com or create an issue in the GitHub repository.

🙏 Acknowledgments

• Gin - HTTP web framework
• GORM - ORM for Go
• Swagger - API documentation
• Testcontainers - Integration testing