CodeSource
/
Readur
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Readur/docs/swagger-ui-guide.md

5.7 KiB
Raw Blame History

🔌 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:

# 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