rachmadiyanti.annisa.3004/antrean-anjungan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README Dokumentation

Browse Source
This commit is contained in:
Meninjar Mulyono
2025-08-14 07:11:46 +07:00
parent 315a240b08
commit 8c6fb0ce48
1 changed files with 281 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

304
README.md
View File

@@ -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 api-service/
make all ├── 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 ```bash
make build git clone <repository-url>
cd api-service
``` ```
Run the application ### 2. Environment Configuration
Create a `.env` file in the project root:
```bash ```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 ```bash
make docker-run make docker-run
``` ```
Shutdown DB Container #### Option B: Manual PostgreSQL Setup
```bash ```bash
make docker-down # Create database
createdb api_service
# Run migrations (if any)
# go run cmd/migrate/main.go
``` ```
DB Integrations Test: ### 5. Run the Application
```bash
make itest
```
Live reload the application: #### Development Mode (with hot reload)
```bash ```bash
make watch 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 <your-jwt-token>
```
## 🧪 Testing
### Unit Tests
```bash ```bash
make test make test
``` ```
Clean up binary from the last build: ### Integration Tests
```bash ```bash
make clean make itest
``` ```
creat swagger
### 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 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