🚀 UGin - Ultimate Gin API Boilerplate

A production-ready REST API boilerplate written in Go with Gin Framework, featuring JWT authentication, GORM ORM, comprehensive middleware support, and interactive Swagger documentation.

✨ Features

🎯 Modern Go - Built with Go 1.23
⚡ Gin Framework - Fast HTTP web framework
🗄️ Multi-Database Support - SQLite, MySQL, PostgreSQL via GORM
🔐 JWT Authentication - Secure token-based authentication
📝 Comprehensive Logging - Application, database, and access logs
🔍 Advanced Querying - Built-in filtering, search, and pagination
🛡️ Security Middleware - CORS, rate limiting, and more
📦 Gzip Compression - Automatic response compression
🔄 Hot Reload - Development mode with auto-reload
📊 Structured Logging - Using logrus
🏗️ Clean Architecture - Repository pattern with dependency injection
🧪 Fully Testable - Interface-based design for easy mocking
🌐 Context Propagation - Proper context handling throughout the stack
♻️ Graceful Shutdown - Proper resource cleanup on exit
📚 Swagger/OpenAPI - Interactive API documentation with Swagger UI

📋 Table of Contents

Quick Start
Project Structure
Configuration
API Endpoints
- Interactive API Documentation (Swagger)
Database
Middleware
Logging
Development
- Swagger Documentation
Docker Support

📚 Additional Documentation

QUICK_START.md - Fast setup guide with common commands
SWAGGER_GUIDE.md - Complete Swagger/OpenAPI documentation guide

🚀 Quick Start

Prerequisites

Go 1.23 or higher
Git

Installation

# Clone the repository
git clone https://github.com/yakuter/ugin.git
cd ugin

# Download dependencies
go mod download

# Build the application
make build

# Run the application
./bin/ugin

Or use the Makefile for a simpler workflow:

# Build and run in one command
make run

# Or run directly without building (development mode)
make run-dev

The server will start at http://127.0.0.1:8081

🎉 Access Swagger UI: http://127.0.0.1:8081/swagger/index.html

📁 Project Structure

ugin/
├── cmd/                      # Application entry points
│   └── ugin/
│       └── main.go           # Main entry point (simple!)
├── internal/                 # Private application code
│   ├── core/                 # Application core
│   │   ├── app.go            # Application lifecycle
│   │   ├── database.go       # Database initialization
│   │   └── router.go         # Router setup
│   ├── domain/               # Domain models (entities)
│   │   ├── post.go
│   │   ├── user.go
│   │   └── auth.go
│   ├── repository/           # Data access layer
│   │   ├── repository.go     # Repository interfaces
│   │   └── gormrepo/         # GORM implementations
│   │       ├── post.go
│   │       └── user.go
│   ├── service/              # Business logic layer
│   │   ├── interfaces.go     # Service interfaces
│   │   ├── post.go
│   │   ├── auth.go
│   │   └── post_test.go      # Example tests
│   ├── handler/              # HTTP handlers
│   │   └── http/
│   │       ├── post.go
│   │       ├── auth.go
│   │       ├── admin.go
│   │       └── middleware.go
│   └── config/               # Configuration management
│       └── config.go
├── pkg/                      # Public reusable packages
│   └── logger/               # Logging utilities
│       └── logger.go
├── containers/               # Docker configuration
│   ├── composes/             # Docker compose files
│   └── images/               # Dockerfiles
├── bin/                      # Compiled binaries (gitignored)
├── config.yml                # Application configuration
├── Makefile                  # Build automation
└── go.mod                    # Go module definition

This structure follows the Standard Go Project Layout with Clean Architecture principles.

Architecture Layers

Core Layer (internal/core/) - Application lifecycle and wiring
Domain Layer (internal/domain/) - Pure business entities
Repository Layer (internal/repository/) - Data access interfaces and implementations
Service Layer (internal/service/) - Business logic and use cases
Handler Layer (internal/handler/) - HTTP request/response handling
Infrastructure (pkg/, internal/config/) - External concerns

Key Principles:

✅ Dependency Injection - No global state
✅ Interface-based - Easy to mock and test
✅ Context Propagation - Proper timeout and cancellation
✅ Clean Separation - Each layer has a single responsibility
✅ Simple main.go - Entry point is just 15 lines!

⚙️ Configuration

Edit config.yml to configure your application:

database:
  driver: "sqlite"      # Options: sqlite, mysql, postgres
  dbname: "ugin"
  username: "user"      # Not required for SQLite
  password: "password"  # Not required for SQLite
  host: "localhost"     # Not required for SQLite
  port: "5432"          # Not required for SQLite
  logmode: true         # Enable SQL query logging

server:
  port: "8081"
  secret: "mySecretKey"                    # JWT secret key
  accessTokenExpireDuration: 1             # Hours
  refreshTokenExpireDuration: 1            # Hours
  limitCountPerRequest: 1                  # Rate limit per request

Database Drivers

SQLite (Default - No setup required):

database:
  driver: "sqlite"
  dbname: "ugin"
  logmode: true

MySQL:

database:
  driver: "mysql"
  dbname: "ugin"
  username: "root"
  password: "password"
  host: "localhost"
  port: "3306"

PostgreSQL:

database:
  driver: "postgres"
  dbname: "ugin"
  username: "user"
  password: "password"
  host: "localhost"
  port: "5432"
  sslmode: "disable"

📡 API Endpoints

All API endpoints are versioned with /api/v1 prefix.

📚 Interactive API Documentation

Swagger UI is available at: http://localhost:8081/swagger/index.html

📖 View all endpoints with detailed documentation
🧪 Test API endpoints directly from browser
🔐 Test authentication with JWT tokens
📋 See request/response examples with real data

See SWAGGER_GUIDE.md for detailed usage.

Authentication Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/v1/auth/signup | Register a new user | | POST | /api/v1/auth/signin | Sign in and get JWT tokens | | POST | /api/v1/auth/refresh | Refresh access token | | POST | /api/v1/auth/check | Validate token |

Posts Endpoints (Public)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/posts | Get all posts (supports pagination) | | GET | /api/v1/posts/:id | Get a single post by ID | | POST | /api/v1/posts | Create a new post | | PUT | /api/v1/posts/:id | Update an existing post | | DELETE | /api/v1/posts/:id | Delete a post |

Posts Endpoints (JWT Protected)

| Method | Endpoint | Description | Auth | |--------|----------|-------------|------| | GET | /api/v1/postsjwt | Get all posts | JWT | | GET | /api/v1/postsjwt/:id | Get a single post | JWT | | POST | /api/v1/postsjwt | Create a new post | JWT | | PUT | /api/v1/postsjwt/:id | Update a post | JWT | | DELETE | /api/v1/postsjwt/:id | Delete a post | JWT |

Admin Endpoints (Basic Auth)

| Method | Endpoint | Description | Auth | |--------|----------|-------------|------| | GET | /admin/dashboard | Admin dashboard | Basic Auth |

Default credentials: username1:password1, username2:password2, username3:password3

Query Parameters

All list endpoints support advanced querying:

GET /posts/?Limit=10&Offset=0&Sort=ID&Order=DESC&Search=keyword

| Parameter | Description | Example | |-----------|-------------|---------| | Limit | Number of records to return | Limit=25 | | Offset | Number of records to skip | Offset=0 | | Sort | Field to sort by | Sort=ID | | Order | Sort order (ASC/DESC) | Order=DESC | | Search | Search keyword | Search=hello |

Example API Requests

Create a Post

curl -X POST http://localhost:8081/api/v1/posts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello World",
    "description": "This is a sample post",
    "tags": [
      {
        "name": "golang",
        "description": "Go programming language"
      },
      {
        "name": "api",
        "description": "REST API"
      }
    ]
  }'

Get Posts with Pagination

curl "http://localhost:8081/api/v1/posts?Limit=10&Offset=0&Sort=id&Order=DESC"

Sign Up

curl -X POST http://localhost:8081/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "master_password": "password123"
  }'

Sign In

curl -X POST http://localhost:8081/api/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "master_password": "password123"
  }'

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "transmission_key": "...",
  "access_token_expires_at": "2025-11-01T10:00:00Z",
  "refresh_token_expires_at": "2025-11-02T10:

Ugin

Install / Use

README