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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user