271 lines
6.0 KiB
Markdown
271 lines
6.0 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 |