https://github.com/camerodev/weatherforecast
Weather Forecast Service
https://github.com/camerodev/weatherforecast
docker gin golang testing
Last synced: 2 months ago
JSON representation
Weather Forecast Service
- Host: GitHub
- URL: https://github.com/camerodev/weatherforecast
- Owner: camerodev
- Created: 2025-06-02T12:49:10.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-02T12:59:02.000Z (about 1 year ago)
- Last Synced: 2025-07-26T13:59:14.982Z (11 months ago)
- Topics: docker, gin, golang, testing
- Language: Go
- Homepage:
- Size: 14.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Weather Forecast Service
A modular and testable Golang HTTP service that retrieves weather data from the National Weather Service API, returning a short forecast and a temperature classification ("hot", "moderate", or "cold"). Built using the Gin framework with a focus on SOLID principles, Swagger documentation, and containerized deployment.
---
## Project Overview
This service exposes an HTTP GET endpoint that:
- Accepts latitude and longitude as query parameters
- Queries the NWS.gov forecast API
- Returns the short forecast and a human-friendly temperature description
- Is suitable for consumption by web clients, monitoring agents, or mobile apps
---
## Features
- RESTful API using Gin
- Integration with the National Weather Service gridpoints API
- Temperature classification logic
- Swagger (OpenAPI 3) documentation
- Fully containerized using Docker and Docker Compose
- Middleware for logging and request validation
- Unit and integration test coverage
- Clean architecture and dependency injection
---
## Project Structure
```
WeatherForecast/
├── cmd/ # Application entry point
│ └── server/
│ └── main.go
├── internal/ # Application logic
│ ├── client/ # Weather API client
│ ├── config/ # Environment configuration loader
│ ├── controller/ # HTTP handlers
│ ├── middleware/ # Logging and validation middleware
│ ├── model/ # Data models and response structs
│ ├── router/ # Route definitions
│ ├── service/ # Business logic
│ └── utils/ # Utility functions (e.g., temperature classification)
├── tests/ # Unit and integration tests
├── API_doc/ # Generated Swagger documentation
├── Dockerfile # Container build configuration
├── docker-compose.yml # Multi-container orchestration
├── go.mod # Go module file
└── README.md # Project documentation
```
---
## Prerequisites
- Go 1.22 or higher
- Docker and Docker Compose
- Swag CLI (for generating Swagger docs)
To install Swag CLI:
```bash
go install github.com/swaggo/swag/cmd/swag@latest
```
---
## Installation & Running Locally
1. Clone the repository:
```bash
git clone https://github.com/camerodev/WeatherForecast.git
cd WeatherForecast
```
2. Install dependencies:
```bash
go mod tidy
```
3. Generate Swagger documentation:
```bash
swag init --generalInfo cmd/server/main.go --output ./API_doc
```
4. Start the server:
```bash
go run cmd/server/main.go
```
5. Test the API:
```bash
curl "http://localhost:8080/api/weather?lat=40.71&lon=-74.01"
```
---
## Usage
### Endpoint
```
GET /api/weather?lat={latitude}&lon={longitude}
```
### Example
```
GET /api/weather?lat=40.71&lon=-74.01
```
### Sample Response
```json
{
"shortForecast": "Partly Cloudy",
"temperature": 72,
"unit": "F",
"feeling": "moderate"
}
```
---
## Testing
Run all tests:
```bash
go test ./...
```
Run only unit tests:
```bash
go test ./tests -run TestWeatherService -v
```
Run integration test against NWS API:
```bash
go test ./tests -run TestLiveNWSClient -v
```
---
## Docker
### Build and run with Docker Compose:
```bash
docker compose up --build
```
This will build and expose the service at:
```
http://localhost:8080/api/weather?lat=40.71&lon=-74.01
```
### Build manually:
```bash
docker build -t weather-forecast .
docker run -p 8080:8080 weather-forecast
```
---
## Swagger
### Generate Swagger documentation:
```bash
swag init --generalInfo cmd/server/main.go --output ./API_doc
```
### Access Swagger UI in browser:
```
http://localhost:8080/api/swagger/index.html
```
---
## Things to Be Improved
If more time were available, the following improvements would be prioritized:
- Add in-memory or Redis caching for repeated forecast lookups
- Support more granular forecast ranges (hourly, 3-day, etc.)
- Add health and metrics endpoints (Prometheus + Grafana support)
- Add support for environment-specific logging levels
- Extend CI to include static analysis and test coverage reporting
- Deploy to Kubernetes with Helm and configure liveness/readiness probes
- Add OpenTelemetry tracing support
- Write Postman or Newman-based integration tests for CI pipelines
---
## Author
Cameron Shahraray
Email: cameron.shahr@gmail.com
GitHub: https://github.com/camerodev
LinkedIn: https://www.linkedin.com/in/cameronmshah