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.
This commit is contained in:
n.nakhostin
2025-08-11 18:24:34 +03:30
parent 566fa07574
commit 3e4831c2e7
23 changed files with 3605 additions and 2087 deletions
+72
View File
@@ -47,6 +47,78 @@ This system implements **Clean Architecture** with:
- **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**
```bash
# 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**
1. Navigate to Swagger UI at `/swagger/`
2. Click "Authorize" button
3. Enter: `Bearer <your_jwt_token>`
4. 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