Skip to content

🔌 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