Files

T

n.nakhostin 3e4831c2e7 Enhance API documentation and restructure routes for improved clarity

- Updated README.md to include comprehensive Swagger documentation details, highlighting new features and endpoint categories.
- Introduced a new router structure to streamline route registration for admin and public endpoints, enhancing maintainability.
- Updated health check endpoint documentation to reflect comprehensive server status information.
- Enhanced customer and company management routes with improved descriptions and examples in Swagger.
- Refactored customer and user handlers to remove obsolete route registrations, aligning with the new router structure.
- Improved response handling in customer and user services to utilize string IDs consistently.
- Updated validation rules and forms for customer management to support multiple company assignments.
- Enhanced logging practices across services to ensure better traceability and error handling.

2025-08-11 18:24:34 +03:30

6.4 KiB

Raw Blame History

Tender Management System

A comprehensive tender management backend system built with Go, following Clean Architecture principles with Domain-Driven Design (DDD) patterns.

📚 Documentation

All documentation has been organized in the docs/ directory for better structure and maintainability.

Quick Links

📖 Main Documentation - Comprehensive project overview and guidelines
🔧 Setup Guides - HTTP server and Swagger setup
🚀 Implementation Details - Architecture and implementation overview
📡 API Examples - API usage examples and endpoints

🚀 Quick Start

Setup Environment
```
# Follow setup guides in docs/setup/
```
Run the Application
```
make run
```
Access API Documentation
- Swagger UI: http://localhost:8081/swagger/index.html
- API Base URL: http://localhost:8081/api/v1

🏗️ Architecture

This system implements Clean Architecture with:

Domain Layer: Business entities and core rules
Service Layer: Business logic and use cases
Handler Layer: HTTP controllers and request handling
Repository Layer: Data access implementations
Infrastructure Layer: External dependencies

📋 Key Features

Clean Architecture: DDD principles with clear separation of concerns
MongoDB Integration: Robust data persistence with proper indexing
Structured Logging: Comprehensive logging with context
Input Validation: Govalidator integration for request validation
Error Handling: Consistent error responses and logging
Time Handling: Unix timestamps throughout the application
API Documentation: Auto-generated Swagger documentation

📋 API Documentation

Swagger/OpenAPI 3.0 Documentation

The Tender Management API features comprehensive, auto-generated Swagger documentation with:

🚀 Version 2.0.0 Features

Comprehensive API Coverage: All endpoints documented with detailed descriptions, examples, and error responses
Interactive API Testing: Built-in Swagger UI for testing endpoints directly from the documentation
Authentication Integration: Bearer token authentication examples and testing capability
Request/Response Examples: Real-world examples for all data structures and API calls
Error Documentation: Detailed error codes, messages, and troubleshooting information

📊 API Endpoints Categories

Health: System monitoring and health check endpoints
Authorization: User authentication, token management, and session handling
Users: Administrative user management with RBAC (Role-Based Access Control)
Customers-Admin: Web panel customer management with advanced filtering
Customers-Authorization: Mobile app customer authentication and profile access
Companies-Admin: Comprehensive company management with search, filtering, and analytics
Companies-Mobile: Mobile-optimized company lookup and information retrieval

🔧 Documentation Access

Local Development: http://localhost:8081/swagger/
Interactive Testing: All endpoints can be tested directly from the Swagger UI
Authentication: Use the "Authorize" button to set Bearer tokens for protected endpoints
Export Options: JSON and YAML formats available for API specifications

📝 Enhanced Features

Detailed Descriptions: Each endpoint includes comprehensive business logic explanations
Parameter Validation: Complete validation rules and constraints for all input parameters
Response Examples: Real-world response examples with proper HTTP status codes
Security Schemes: JWT Bearer token authentication clearly documented
Error Handling: Comprehensive error response documentation with troubleshooting guides
Filtering & Pagination: Advanced query parameters for list endpoints with examples
Business Logic: Context-aware descriptions explaining when and how to use each endpoint

🏗️ Technical Specifications

OpenAPI/Swagger 2.0: Industry-standard API documentation format
Auto-Generation: Documentation automatically updated from code annotations
Type Safety: Strong typing with Go struct validation and examples
Validation Rules: Complete govalidator integration for request validation
Consistent Response Format: Standardized API response structure with metadata

💡 Usage Examples

# Access Swagger UI
curl http://localhost:8081/swagger/

# Download API specification
curl http://localhost:8081/swagger/doc.json

# Test authentication endpoint
curl -X POST "http://localhost:8081/admin/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

🔐 Authentication Testing

Navigate to Swagger UI at /swagger/
Click "Authorize" button
Enter: Bearer <your_jwt_token>
Test protected endpoints directly from the interface

API Design Principles

RESTful Design: Consistent REST principles with proper HTTP methods and status codes
Clean Architecture: Domain-driven design with clear separation of concerns
Validation: Comprehensive input validation with meaningful error messages
Security: JWT-based authentication with proper token management
Performance: Optimized queries with pagination and filtering capabilities
Maintainability: Auto-generated documentation stays in sync with code changes

🔧 Development

Prerequisites

Go 1.23+
MongoDB 4.4+
Valid MongoDB connection

Project Structure

tm_back/
├── cmd/web/                    # Application entry point
├── internal/                   # Private application code
│   ├── customer/              # Customer domain
│   └── ...                    # Other domains
├── pkg/                       # Public packages
│   ├── logger/               # Logging utilities
│   ├── mongo/                # MongoDB utilities
│   └── response/             # API response utilities
├── docs/                      # 📚 All documentation
└── config.yaml               # Configuration file

📞 Support

For detailed documentation, guides, and examples, please visit the docs/ directory.

Version: 1.0.0
Last Updated: $(date)

6.4 KiB Raw Blame History