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

Feature Development

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

Testing
```
make test
make itest
```
Code Quality
```
go fmt ./...
go vet ./...
```
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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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