144 lines
5.7 KiB
Markdown
144 lines
5.7 KiB
Markdown
# 🔌 Swagger UI Guide
|
|
|
|
Readur includes built-in Swagger UI for interactive API documentation and testing. Access it easily through your user profile menu.
|
|
|
|
## Accessing Swagger UI
|
|
|
|
1. **Login to Readur** - Authenticate with your user credentials
|
|
2. **Click Your Profile** - Click on your profile avatar in the top-right corner
|
|
3. **Select "API Documentation"** - Choose the Swagger UI option from the dropdown menu
|
|
4. **Interactive Documentation** - Explore and test all available API endpoints
|
|
|
|
## API Documentation Features
|
|
|
|
### Endpoint Explorer
|
|
- **Complete API Reference** - All REST endpoints with detailed descriptions
|
|
- **Request/Response Examples** - Sample data for every endpoint
|
|
- **Parameter Details** - Required and optional parameters with types
|
|
- **Authentication Info** - JWT token requirements and usage
|
|
|
|
### Interactive Testing
|
|
- **Try It Out** - Execute API calls directly from the documentation
|
|
- **Real Data** - Test with your actual Readur data and configuration
|
|
- **Response Validation** - See actual responses and status codes
|
|
- **Error Handling** - View error responses and troubleshooting info
|
|
|
|
## API Categories
|
|
|
|
### Authentication
|
|
- **Login/Logout** - User authentication endpoints
|
|
- **Token Management** - JWT token refresh and validation
|
|
- **User Registration** - New user account creation
|
|
- **Password Reset** - Password recovery workflows
|
|
|
|
### Document Management
|
|
- **Upload Documents** - Single and batch file upload endpoints
|
|
- **Document Retrieval** - Get document metadata and content
|
|
- **Document Search** - Full-text search with various modes
|
|
- **Document Operations** - Update, delete, and organize documents
|
|
|
|
### User Management
|
|
- **User CRUD** - Create, read, update, delete user accounts
|
|
- **Role Management** - Assign and modify user roles
|
|
- **Permission Control** - Manage access rights and restrictions
|
|
- **User Preferences** - Personal settings and configurations
|
|
|
|
### Source Management
|
|
- **Source Configuration** - WebDAV, S3, and local folder setup
|
|
- **Sync Operations** - Manual and automated synchronization
|
|
- **Source Health** - Status monitoring and health checks
|
|
- **Source Statistics** - Usage metrics and performance data
|
|
|
|
### System Administration
|
|
- **Health Monitoring** - System status and performance metrics
|
|
- **Analytics Data** - Usage statistics and reporting endpoints
|
|
- **Configuration** - System settings and environment variables
|
|
- **Maintenance** - Backup, cleanup, and administrative tasks
|
|
|
|
## Authentication in Swagger UI
|
|
|
|
### Using JWT Tokens
|
|
1. **Login via API** - Use `/api/auth/login` endpoint to get a JWT token
|
|
2. **Copy Token** - Copy the returned JWT token
|
|
3. **Authorize** - Click the "Authorize" button in Swagger UI
|
|
4. **Enter Token** - Paste your JWT token in the format: `Bearer your_token_here`
|
|
5. **Test Endpoints** - All authenticated endpoints now work with your credentials
|
|
|
|
### Token Management
|
|
- **Token Expiry** - Tokens expire after a configured time period
|
|
- **Refresh Tokens** - Use refresh token endpoint to get new access tokens
|
|
- **Logout** - Invalidate tokens using the logout endpoint
|
|
- **Multiple Sessions** - Each browser session needs its own token
|
|
|
|
## Best Practices
|
|
|
|
### Development Usage
|
|
- **Test First** - Use Swagger UI to test API endpoints before implementing
|
|
- **Validate Responses** - Check response formats match your expectations
|
|
- **Error Scenarios** - Test error conditions and edge cases
|
|
- **Performance Testing** - Monitor response times for optimization
|
|
|
|
### Production Considerations
|
|
- **Access Control** - Swagger UI respects the same authentication as the main app
|
|
- **Rate Limiting** - API rate limits apply to Swagger UI requests
|
|
- **Logging** - All API calls from Swagger UI are logged normally
|
|
- **Security** - Use HTTPS in production for secure token transmission
|
|
|
|
## Common Use Cases
|
|
|
|
### Frontend Development
|
|
- **API Integration** - Test endpoints before implementing in your frontend
|
|
- **Data Formats** - Understand expected request/response formats
|
|
- **Error Handling** - Learn about error codes and messages
|
|
- **Feature Testing** - Validate new features work as expected
|
|
|
|
### System Integration
|
|
- **Third-party Tools** - Test integration with external systems
|
|
- **Automation Scripts** - Develop scripts using API documentation
|
|
- **Monitoring Systems** - Integrate health check endpoints
|
|
- **Data Migration** - Use bulk operations for data import/export
|
|
|
|
### Troubleshooting
|
|
- **Debug Issues** - Test API calls to isolate problems
|
|
- **Validate Permissions** - Check if user roles have correct access
|
|
- **Network Testing** - Verify connectivity and response times
|
|
- **Data Verification** - Confirm data integrity and processing status
|
|
|
|
## Advanced Features
|
|
|
|
### Custom Headers
|
|
- **Request Customization** - Add custom headers to API requests
|
|
- **Content-Type** - Specify different content types for uploads
|
|
- **User-Agent** - Set custom user agent strings
|
|
- **Cache Control** - Control caching behavior for responses
|
|
|
|
### Bulk Operations
|
|
- **Batch Uploads** - Test multiple file uploads simultaneously
|
|
- **Bulk Updates** - Update multiple documents or users at once
|
|
- **Mass Operations** - Perform administrative tasks in bulk
|
|
- **Data Export** - Export large datasets via API
|
|
|
|
## Configuration Options
|
|
|
|
Administrators can configure Swagger UI access:
|
|
|
|
```env
|
|
# Enable/disable Swagger UI
|
|
SWAGGER_UI_ENABLED=true
|
|
|
|
# Customize Swagger UI path
|
|
SWAGGER_UI_PATH=/docs
|
|
|
|
# Authentication requirements
|
|
SWAGGER_REQUIRE_AUTH=true
|
|
|
|
# Rate limiting for API documentation
|
|
SWAGGER_RATE_LIMIT=1000
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- **Authentication Required** - Swagger UI requires the same login as the main application
|
|
- **Role-Based Access** - API endpoints respect user role permissions
|
|
- **Audit Logging** - All API calls are logged for security monitoring
|
|
- **Token Security** - JWT tokens should be kept secure and not shared |