OpenAPI Showcase

A production-grade monorepo containing 5 fully documented FastAPI applications demonstrating modern backend development best practices.

🚀 One-Click Deploy

📋 Features

5 Production-Ready APIs - Auth, Orders, File Processor, Notifications, Webhook Tester
Complete OpenAPI 3.1 Documentation - Swagger UI, Redoc, and Stoplight Elements
JWT Authentication - Secure token-based auth with refresh token rotation
Background Task Processing - Celery with Redis for async operations
Real-time Communication - WebSocket and Server-Sent Events support
Rate Limiting - Redis-backed distributed rate limiting
Cursor Pagination - Efficient pagination for large datasets
Property-Based Testing - Comprehensive test suite with Hypothesis

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Client Layer                              │
│              (Web Apps, Mobile Apps, External Services)          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     API Gateway / Load Balancer                  │
└─────────────────────────────────────────────────────────────────┘
                                │
        ┌───────────┬───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
   │  Auth   │ │ Orders  │ │  Files  │ │ Notif.  │ │ Webhook │
   │  :8001  │ │  :8002  │ │  :8003  │ │  :8004  │ │  :8005  │
   └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
        │           │           │           │           │
        └───────────┴───────────┼───────────┴───────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
             ┌────────────┐          ┌────────────┐
             │ PostgreSQL │          │   Redis    │
             │     16     │          │     7      │
             └────────────┘          └────────────┘
                                           │
                                    ┌──────┴──────┐
                                    ▼             ▼
                              ┌──────────┐  ┌──────────┐
                              │  Celery  │  │  Flower  │
                              │ Workers  │  │  :5555   │
                              └──────────┘  └──────────┘

📚 API Documentation

Each API provides interactive documentation at multiple endpoints:

API	Swagger UI	Redoc	Stoplight
Auth	/docs	/redoc	/stoplight
Orders	/docs	/redoc	/stoplight
File Processor	/docs	/redoc	/stoplight
Notifications	/docs	/redoc	/stoplight
Webhook Tester	/docs	/redoc	/stoplight

🚀 Quick Start

Prerequisites

Python 3.11+
Docker and Docker Compose
Make (optional, for convenience commands)

Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/example/openapi-showcase.git
cd openapi-showcase

# Copy environment file
cp .env.example .env

# Start all services
docker compose up --build

# In a new terminal, seed the database with test data
docker compose exec auth-api python scripts/seed_data.py

# Services will be available at:
# - Auth API:          http://localhost:8001
# - Orders API:        http://localhost:8002
# - File Processor:    http://localhost:8003
# - Notifications:     http://localhost:8004
# - Webhook Tester:    http://localhost:8005
# - Flower Dashboard:  http://localhost:5555

Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Start PostgreSQL and Redis (using Docker)
docker compose up -d postgres redis

# Run database migrations
alembic upgrade head

# Start individual APIs
uvicorn apps.auth.main:app --reload --port 8001
uvicorn apps.orders.main:app --reload --port 8002
uvicorn apps.file_processor.main:app --reload --port 8003
uvicorn apps.notifications.main:app --reload --port 8004
uvicorn apps.webhook_tester.main:app --reload --port 8005

🧪 Testing

Run All Tests

# Using Make
make test

# Using pytest directly
pytest tests/ -v

# With coverage report
pytest tests/ --cov=apps --cov=shared --cov-report=html

Run Specific Test Categories

# Unit tests only
pytest tests/ -m unit

# Property-based tests only
pytest tests/ -m property

# Integration tests only
pytest tests/ -m integration

Test Each API

# Test Auth API
pytest tests/properties/test_auth_properties.py -v

# Test Orders API
pytest tests/properties/test_orders_properties.py -v

# Test File Processor API
pytest tests/properties/test_file_processor_properties.py -v

# Test Notifications API
pytest tests/properties/test_notifications_properties.py -v

# Test Webhook Tester API
pytest tests/properties/test_webhook_tester_properties.py -v

🌱 Seed Data

The project includes a seed script to populate the database with test data for development and testing.

Running the Seed Script

# With Docker Compose (recommended)
docker compose exec auth-api python scripts/seed_data.py

# Local development
python scripts/seed_data.py

Test Credentials

After running the seed script, you can use these credentials:

Role	Email	Password
Admin	admin@example.com	Admin123!
User	john.doe@example.com	Password123!
User	jane.smith@example.com	Password123!
User	bob.wilson@example.com	Password123!
User	alice.johnson@example.com	Password123!

Seeded Data Overview

The seed script creates:

5 Users - 1 admin and 4 regular users
12 Orders - 3 orders per regular user with various statuses
5 Webhook Events - Sample Stripe and GitHub webhook events
5 Files - Sample uploaded files with conversion jobs
12 Notifications - 3 notifications per regular user
2 Webhook Bins - With 5 captured events each

📖 API Usage Examples

Authentication

# Register a new user
curl -X POST http://localhost:8001/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123!", "full_name": "John Doe"}'

# Login
curl -X POST http://localhost:8001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123!"}'

# Get current user (with token)
curl http://localhost:8001/users/me \
  -H "Authorization: Bearer <access_token>"

Orders API

# Create an order
curl -X POST http://localhost:8002/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"product_id": "prod_123", "quantity": 2, "unit_price": 29.99}],
    "shipping_address": {"street": "123 Main St", "city": "NYC", "zip": "10001"}
  }'

# List orders with pagination
curl "http://localhost:8002/orders?limit=10" \
  -H "Authorization: Bearer <access_token>"

# Filter orders by status
curl "http://localhost:8002/orders?status=pending" \
  -H "Authorization: Bearer <access_token>"

File Processor API

# Upload a file
curl -X POST http://localhost:8003/uploads \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@document.pdf"

# Request file conversion
curl -X POST http://localhost:8003/files/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "<file_uuid>", "target_format": "png"}'

# Check conversion status
curl http://localhost:8003/files/<file_uuid>/status \
  -H "Authorization: Bearer <access_token>"

Notifications API

# Connect to WebSocket for real-time notifications
websocat "ws://localhost:8004/ws/notifications?token=<access_token>"

# Get notification history
curl http://localhost:8004/notifications \
  -H "Authorization: Bearer <access_token>"

# Send a notification (admin)
curl -X POST http://localhost:8004/notifications \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"user_ids": ["<user_uuid>"], "title": "Hello", "message": "Test notification"}'

Webhook Tester API

# Create a webhook bin
curl -X POST http://localhost:8005/bins \
  -H "Authorization: Bearer <access_token>"

# Send a test webhook to the bin
curl -X POST http://localhost:8005/<bin_id> \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"key": "value"}}'

# List captured events
curl http://localhost:8005/<bin_id>/events \
  -H "Authorization: Bearer <access_token>"

📁 Project Structure

openapi-showcase/
├── apps/                          # Application modules
│   ├── auth/                      # Authentication API
│   │   ├── main.py               # FastAPI app instance
│   │   ├── config.py             # Auth-specific settings
│   │   ├── routes/               # API endpoints
│   │   ├── services/             # Business logic
│   │   ├── models/               # SQLModel definitions
│   │   └── schemas/              # Pydantic schemas
│   ├── orders/                    # E-commerce Orders API
│   ├── file_processor/            # File Processing API
│   ├── notifications/             # Real-time Notifications API
│   ├── webhook_tester/            # Webhook Testing API
│   └── gateway/                   # API Gateway
├── shared/                        # Shared utilities
│   ├── auth/                      # JWT & password utilities
│   ├── database/                  # Database connection
│   ├── pagination/                # Cursor pagination
│   ├── rate_limit/                # Rate limiting
│   ├── middleware/                # CORS, trusted hosts
│   ├── exceptions/                # Error handling
│   └── schemas/                   # Common schemas
├── tests/                         # Test suite
│   ├── properties/                # Property-based tests
│   ├── unit/                      # Unit tests
│   └── integration/               # Integration tests
├── migrations/                    # Alembic migrations
├── docs/                          # Documentation
├── scripts/                       # Utility scripts
├── .github/workflows/             # CI/CD pipelines
├── docker-compose.yml             # Docker services
├── Dockerfile                     # Container build
├── pyproject.toml                 # Project configuration
├── render.yaml                    # Render deployment
├── fly.toml                       # Fly.io deployment
└── railway.json                   # Railway deployment

🔧 Configuration

Environment Variables

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	`postgresql+asyncpg://postgres:postgres@localhost:5432/openapi_showcase`
`REDIS_URL`	Redis connection string	`redis://localhost:6379/0`
`SECRET_KEY`	JWT signing key	(required in production)
`ENVIRONMENT`	Environment name	`development`
`ACCESS_TOKEN_EXPIRE_MINUTES`	JWT access token expiry	`15`
`REFRESH_TOKEN_EXPIRE_DAYS`	JWT refresh token expiry	`7`
`RATE_LIMIT_PER_MINUTE`	Rate limit per IP	`100`
`CORS_ORIGINS`	Allowed CORS origins	`*`

🛠️ Development Commands

# Start development environment
make dev

# Run tests
make test

# Run linting
make lint

# Format code
make format

# Run database migrations
make migrate

# Open database shell
make db-shell

# Build Docker images
make build

# Clean up
make clean

🔒 Security Features

JWT Authentication - Access tokens (15min) and refresh tokens (7 days)
Password Hashing - bcrypt with automatic salt
Rate Limiting - Redis-backed distributed rate limiting
CORS Protection - Configurable allowed origins
Trusted Hosts - Host header validation
Webhook Signatures - HMAC-SHA256 verification

📊 Monitoring

Health Checks - /health endpoint on each API
Flower Dashboard - Celery task monitoring at :5555
Structured Logging - JSON logs for easy parsing
Request Tracing - Request ID propagation

📋 Comprehensive API Testing Guide

This section provides detailed instructions for testing each API endpoint.

Prerequisites for Testing

Start all services: docker compose up --build
Seed the database: docker compose exec auth-api python scripts/seed_data.py
Get an access token by logging in (see Authentication section below)

1. Auth API Testing (Port 8001)

# Health check
curl http://localhost:8001/health

# Register a new user
curl -X POST http://localhost:8001/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "newuser@example.com", "password": "SecurePass123!", "full_name": "New User"}'

# Login with seeded user
curl -X POST http://localhost:8001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "john.doe@example.com", "password": "Password123!"}'
# Save the access_token from response

# Get current user profile
curl http://localhost:8001/users/me \
  -H "Authorization: Bearer <access_token>"

# Refresh token
curl -X POST http://localhost:8001/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token>"}'

# Logout
curl -X POST http://localhost:8001/auth/logout \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<refresh_token>"}'

2. Orders API Testing (Port 8002)

# Health check
curl http://localhost:8002/health

# List all orders (requires auth)
curl http://localhost:8002/orders \
  -H "Authorization: Bearer <access_token>"

# List orders with pagination
curl "http://localhost:8002/orders?limit=5" \
  -H "Authorization: Bearer <access_token>"

# Filter orders by status
curl "http://localhost:8002/orders?status=pending" \
  -H "Authorization: Bearer <access_token>"

# Filter orders by date range
curl "http://localhost:8002/orders?start_date=2024-01-01&end_date=2024-12-31" \
  -H "Authorization: Bearer <access_token>"

# Create a new order
curl -X POST http://localhost:8002/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": "PROD-001", "product_name": "Widget", "quantity": 2, "unit_price": 29.99}
    ],
    "shipping_address": {"street": "123 Main St", "city": "New York", "state": "NY", "zip": "10001"},
    "billing_address": {"street": "123 Main St", "city": "New York", "state": "NY", "zip": "10001"}
  }'

# Get specific order
curl http://localhost:8002/orders/<order_id> \
  -H "Authorization: Bearer <access_token>"

# Update order status
curl -X PATCH http://localhost:8002/orders/<order_id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed"}'

# List webhook events
curl http://localhost:8002/webhooks \
  -H "Authorization: Bearer <access_token>"

3. File Processor API Testing (Port 8003)

# Health check
curl http://localhost:8003/health

# Upload a file
curl -X POST http://localhost:8003/uploads \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@/path/to/your/file.pdf"

# Get signed URL for direct upload
curl -X POST http://localhost:8003/uploads/signed-url \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "document.pdf", "content_type": "application/pdf"}'

# Request file conversion
curl -X POST http://localhost:8003/files/convert \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "<file_uuid>", "target_format": "png"}'

# Check conversion status
curl http://localhost:8003/files/<file_id>/status \
  -H "Authorization: Bearer <access_token>"

# List user's files
curl http://localhost:8003/files \
  -H "Authorization: Bearer <access_token>"

4. Notifications API Testing (Port 8004)

# Health check
curl http://localhost:8004/health

# Get notification history
curl http://localhost:8004/notifications \
  -H "Authorization: Bearer <access_token>"

# Get notifications with pagination
curl "http://localhost:8004/notifications?limit=10" \
  -H "Authorization: Bearer <access_token>"

# Send notification (admin only)
curl -X POST http://localhost:8004/notifications \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["<user_uuid>"],
    "title": "Test Notification",
    "message": "This is a test notification",
    "type": "info"
  }'

# Mark notification as read
curl -X PATCH http://localhost:8004/notifications/<notification_id>/read \
  -H "Authorization: Bearer <access_token>"

# WebSocket connection (use websocat or similar tool)
websocat "ws://localhost:8004/ws/notifications?token=<access_token>"

# Server-Sent Events connection
curl http://localhost:8004/events \
  -H "Authorization: Bearer <access_token>"

5. Webhook Tester API Testing (Port 8005)

# Health check
curl http://localhost:8005/health

# Create a webhook bin
curl -X POST http://localhost:8005/bins \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Test Bin"}'

# List user's bins
curl http://localhost:8005/bins \
  -H "Authorization: Bearer <access_token>"

# Send a test webhook to a bin (no auth required)
curl -X POST http://localhost:8005/<bin_id> \
  -H "Content-Type: application/json" \
  -H "X-Custom-Header: test-value" \
  -d '{"event": "order.created", "data": {"order_id": "12345", "amount": 99.99}}'

# List captured events for a bin
curl http://localhost:8005/<bin_id>/events \
  -H "Authorization: Bearer <access_token>"

# Delete a bin
curl -X DELETE http://localhost:8005/bins/<bin_id> \
  -H "Authorization: Bearer <access_token>"

Testing with Swagger UI

Each API provides interactive Swagger UI documentation:

Auth API: http://localhost:8001/docs
Orders API: http://localhost:8002/docs
File Processor API: http://localhost:8003/docs
Notifications API: http://localhost:8004/docs
Webhook Tester API: http://localhost:8005/docs

To test authenticated endpoints in Swagger UI:

Click the "Authorize" button
Enter your access token in the format: Bearer <your_token>
Click "Authorize" to save
Now you can test protected endpoints

Running Automated Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=apps --cov=shared --cov-report=html --cov-report=term

# Run specific test file
pytest tests/properties/test_auth_properties.py -v

# Run tests matching a pattern
pytest tests/ -k "test_password" -v

# Run tests with detailed output
pytest tests/ -v --tb=long

# Run tests in parallel (requires pytest-xdist)
pytest tests/ -n auto

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

FastAPI - Modern Python web framework
SQLModel - SQL databases with Python types
Pydantic - Data validation using Python type hints
Celery - Distributed task queue
Hypothesis - Property-based testing

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github/workflows		.github/workflows
apps		apps
docs		docs
migrations		migrations
scripts		scripts
shared		shared
tests		tests
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
fly.toml		fly.toml
pyproject.toml		pyproject.toml
railway.json		railway.json
render.yaml		render.yaml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

OpenAPI Showcase

🚀 One-Click Deploy

📋 Features

🏗️ Architecture

📚 API Documentation

🚀 Quick Start

Prerequisites

Using Docker Compose (Recommended)

Local Development

🧪 Testing

Run All Tests

Run Specific Test Categories

Test Each API

🌱 Seed Data

Running the Seed Script

Test Credentials

Seeded Data Overview

📖 API Usage Examples

Authentication

Orders API

File Processor API

Notifications API

Webhook Tester API

📁 Project Structure

🔧 Configuration

Environment Variables

🛠️ Development Commands

🔒 Security Features

📊 Monitoring

📋 Comprehensive API Testing Guide

Prerequisites for Testing

1. Auth API Testing (Port 8001)

2. Orders API Testing (Port 8002)

3. File Processor API Testing (Port 8003)

4. Notifications API Testing (Port 8004)

5. Webhook Tester API Testing (Port 8005)

Testing with Swagger UI

Running Automated Tests

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages