🧪 RESTful API with Go and Gin

Proof of Concept for a RESTful API built with Go and Gin. Manage football player data with SQLite, GORM, Swagger documentation, and in-memory caching.

Table of Contents

• Features
• Tech Stack
• Project Structure
• Architecture
• API Reference
• Prerequisites
• Quick Start
• Testing
• Docker
• Environment Variables
• Command Summary
• Contributing
• Legal

Features

• 🔌 RESTful CRUD operations for football player data
• 📚 Interactive API documentation with Swagger UI and Postman collection
• 🩺 Health check endpoint for monitoring
• ⚡ In-memory caching (1-hour TTL)
• 💿 Relational database with ORM
• ✅ Comprehensive integration tests
• 🐳 Full containerization support
• 🔄 CI/CD pipeline with automated testing and deployment

Tech Stack

Category	Technology
Language	Go 1.24.1
Web Framework	Gin
ORM	GORM
Database	SQLite
Caching	gin-contrib/cache
API Documentation	Swagger/OpenAPI
Testing	testify
Containerization	Docker & Docker Compose

Project Structure

/
├── main.go                 # Entry point: DB connection, route setup, server start
├── controller/             # HTTP handlers (request/response logic)
│   └── player_controller.go
├── service/                # Business logic (ORM interactions)
│   └── player_service.go
├── route/                  # Route configuration and middleware
│   ├── player_route.go     # Route setup with caching middleware
│   └── path.go             # Path constants
├── model/                  # Data structures
│   └── player_model.go
├── data/                   # Database connection
│   └── player_data.go
├── swagger/                # Swagger configuration
│   └── swagger.go
├── docs/                   # Auto-generated Swagger docs (DO NOT EDIT)
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── tests/                  # Integration tests
│   ├── main_test.go
│   ├── player_fake.go
│   └── players.json
├── storage/                # SQLite database file (pre-seeded)
├── scripts/                # Container entrypoint & healthcheck
└── .github/workflows/      # CI/CD pipelines

Architecture

%%{init: {
  "theme": "default",
  "themeVariables": {
    "fontFamily": "Fira Code, Consolas, monospace",
    "textColor": "#555",
    "lineColor": "#555",
    "lineWidth": 2
  }
}}%%

graph BT
    %% Packages
    model[model]
    data[data]
    service[service]
    controller[controller]
    route[route]
    main[main]

    %% External Dependencies
    gin[Gin]
    gorm[GORM]

    %% Tests and Documentation
    tests[tests]
    docs[docs]

    %% Main Application Flow
    data --> service
    service --> controller
    controller --> route
    route --> main

    model --> data
    model --> controller

    %% External Dependencies connections
    gorm --> data
    gin --> controller
    gin --> route

    %% Tests and Documentation connections
    main -.-> tests
    docs --> route

    %% Node styling (fallbacks)
    classDef core fill:#b3d9ff,stroke:#6db1ff,stroke-width:2px,color:#555,font-family:monospace;
    classDef deps fill:#ffcccc,stroke:#ff8f8f,stroke-width:2px,color:#555,font-family:monospace;
    classDef test fill:#ccffcc,stroke:#53c45e,stroke-width:2px,color:#555,font-family:monospace;
    classDef swag fill:#ffffcc,stroke:#fdce15,stroke-width:2px,color:#555,font-family:monospace;

    class main,route,controller,service,data,model core
    class gin,gorm deps
    class tests test
    class docs swag

Loading

Layered architecture with clear separation of concerns. Dependencies flow from data layer through services and controllers to routes. External dependencies (Gin and GORM) integrate at their respective layers. Integration tests (dotted lines) validate the complete application.

API Reference

Interactive API documentation is available via Swagger UI at http://localhost:9000/swagger/index.html when the server is running.

💡 Note: The Swagger documentation is automatically generated from code annotations using swaggo/swag. To regenerate after making changes, run swag init.

Quick Reference:

• GET /players - List all players
• GET /players/:id - Get player by ID
• GET /players/squadnumber/:squadnumber - Get player by squad number
• POST /players - Create new player
• PUT /players/:id - Update player
• DELETE /players/:id - Remove player
• GET /health - Health check

For complete endpoint documentation with request/response schemas, explore the interactive Swagger UI. You can also access the OpenAPI JSON specification at http://localhost:9000/swagger.json.

Postman Collection

A pre-configured Postman collection is available at postman-collections/go-samples-gin-restful.postman_collection.json.

Prerequisites

Before you begin, ensure you have the following installed:

• Go 1.24.0 or higher
• Docker & Docker Compose (optional, for containerized deployment)

Quick Start

Clone the repository

git clone https://github.com/nanotaboada/go-samples-gin-restful.git
cd go-samples-gin-restful

Install dependencies

go mod download

Start the development server

go run .

The server will start on http://localhost:9000.

Access the application

• API: http://localhost:9000
• Swagger Documentation: http://localhost:9000/swagger/index.html
• Health Check: http://localhost:9000/health

Testing

Run the test suite with coverage:

# Run all tests
go test ./...

# Run tests with coverage
go test -v ./... -coverprofile=coverage.out

# Run tests with detailed coverage for specific packages
go test -v ./... \
  -coverpkg=github.com/nanotaboada/go-samples-gin-restful/service,github.com/nanotaboada/go-samples-gin-restful/controller,github.com/nanotaboada/go-samples-gin-restful/route \
  -covermode=atomic \
  -coverprofile=coverage.out

# View coverage report
go tool cover -html=coverage.out

Tests are located in the tests/ directory and use testify for integration testing. Coverage reports are generated for controllers, services, and routes only.

Coverage targets: 80% minimum for service, controller, and route packages.

Docker

This project includes full Docker support with multi-stage builds and Docker Compose for easy deployment.

Build the Docker image

docker compose build

Start the application

docker compose up

💡 Note: On first run, the container copies a pre-seeded SQLite database into a persistent volume. On subsequent runs, that volume is reused and the data is preserved.

Stop the application

docker compose down

Reset the database

To remove the volume and reinitialize the database from the built-in seed file:

docker compose down -v

The containerized application runs on port 9000 and includes health checks that monitor the /health endpoint every 30 seconds.

Environment Variables

The application can be configured using the following environment variables (declared in compose.yaml):

# Database storage path (default: ./storage/players-sqlite3.db)
# In Docker: /storage/players-sqlite3.db
STORAGE_PATH=./storage/players-sqlite3.db

# Gin framework mode: debug, release, or test (default: debug)
# In Docker: release
GIN_MODE=release

Command Summary

Command	Description
go run .	Start development server
go build	Build the application
go test ./...	Run all tests
go test -v ./... -coverprofile=coverage.out	Run tests with coverage report
go fmt ./...	Format code
go mod tidy	Clean up dependencies
swag init	Regenerate Swagger documentation
docker compose build	Build Docker image
docker compose up	Start Docker container
docker compose down	Stop Docker container
docker compose down -v	Stop and remove Docker volume

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on the code of conduct and the process for submitting pull requests.

Key guidelines:

• Follow Conventional Commits for commit messages
• Ensure all tests pass (go test ./...)
• Run go fmt before committing
• Keep changes small and focused

Legal

This project is provided for educational and demonstration purposes and may be used in production environments at your discretion. All referenced trademarks, service marks, product names, company names, and logos are the property of their respective owners and are used solely for identification or illustrative purposes.