README Dokumentation

2025-08-14 07:11:46 +07:00
parent 315a240b08
commit 8c6fb0ce48
1 changed files with 281 additions and 25 deletions
--- 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 <repository-url>
+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 <your-jwt-token>
+```
+
+## 🧪 Testing
+
+### Unit Tests
 ```bash
 make test
 ```

-Clean up binary from the last build:
+### Integration Tests
 ```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
+```
+
+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