diff --git a/README.md b/README.md index 03fe57f..f8b1a0a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,311 @@ -# Project api-service +# API Service -One Paragraph of project description goes here +A comprehensive Go-based REST API service built with Gin framework, featuring PostgreSQL database integration, JWT authentication, Swagger documentation, WebSocket support, and containerized deployment. -## Getting Started +## ๐Ÿš€ Features -These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system. +- **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 -## MakeFile +## ๐Ÿ—๏ธ Architecture -Run build make command with tests -```bash -make all +``` +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 ``` -Build the application +## ๐Ÿ› ๏ธ 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 + ```bash -make build +git clone +cd api-service ``` -Run the application +### 2. Environment Configuration + +Create a `.env` file in the project root: + ```bash -make run +# 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 ``` -Create DB container + +### 3. Install Dependencies + +```bash +go mod download +``` + +### 4. Database Setup + +#### Option A: Using Docker Compose (Recommended) ```bash make docker-run ``` -Shutdown DB Container +#### Option B: Manual PostgreSQL Setup ```bash -make docker-down +# Create database +createdb api_service + +# Run migrations (if any) +# go run cmd/migrate/main.go ``` -DB Integrations Test: -```bash -make itest -``` +### 5. Run the Application -Live reload the application: +#### Development Mode (with hot reload) ```bash make watch ``` -Run the test suite: +#### Production Mode +```bash +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 +``` + +## ๐Ÿงช Testing + +### Unit Tests ```bash make test ``` -Clean up binary from the last build: +### Integration Tests ```bash -make clean +make itest ``` -creat swagger -swag init -g cmd/api/main.go --output cmd/api/docs \ No newline at end of file + +### Run All Tests +```bash +make all +``` + +## ๐Ÿณ Docker Deployment + +### Build and Run with Docker Compose +```bash +# Development +make docker-run + +# Production +docker-compose -f docker-compose.yml up --build -d +``` + +### Docker Commands +```bash +# 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** + ```bash + git checkout -b feature/your-feature + make watch # Start development server with hot reload + ``` + +2. **Testing** + ```bash + make test + make itest + ``` + +3. **Code Quality** + ```bash + go fmt ./... + go vet ./... + ``` + +4. **Build & Run** + ```bash + 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: +```bash +swag init -g cmd/api/main.go --output cmd/api/docs +``` + +This command will: +- Scan your Go source code for Swagger annotations +- Generate OpenAPI 3.0 specification files +- Create/update the documentation in `cmd/api/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: +```bash +GIN_MODE=release +PORT=8080 +``` + +### Docker Production +```bash +docker build -t api-service:prod . +docker run -d -p 8080:8080 --env-file .env api-service:prod +``` + +### Health Check +```bash +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](LICENSE) file for details. + +## ๐Ÿ†˜ Support + +For support, email support@example.com or create an issue in the GitHub repository. + +## ๐Ÿ™ Acknowledgments + +- [Gin](https://github.com/gin-gonic/gin) - HTTP web framework +- [GORM](https://gorm.io/) - ORM for Go +- [Swagger](https://swagger.io/) - API documentation +- [Testcontainers](https://testcontainers.com/) - Integration testing