FastAPI Environment Banner

A lightweight and simple library for adding visual environment banners to FastAPI applications.
Inspired by django-env-notice, but specifically designed for FastAPI with a focus on simplicity and ease of integration.

---

See it in action

Visual environment indicators help prevent mistakes by clearly showing which environment you're working in

---

Features

• Simple and Lightweight: Just a few lines of code to integrate
• Visual and Intuitive: Colorful banners that clearly differentiate environments
• Highly Configurable: Customize colors, texts, and positions
• Swagger UI Support: Banner also appears in API documentation
• Zero Configuration: Works out-of-the-box with sensible defaults
• Secure: Banner disabled in production by default

Documentation

Full documentation is available at pinnlabs.github.io/fastapi-env-banner

Installation

pip install fastapi-env-banner

or if you are using uv:

uv add fastapi-env-banner

Basic Setup

from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware, setup_swagger_ui

# Create FastAPI application
app = FastAPI(title="My API")

# Configure banner (auto-detects from ENVIRONMENT variable)
config = EnvBannerConfig.from_env()

# Add middleware
app.add_middleware(EnvBannerMiddleware, config=config)

# Setup Swagger UI with banner
setup_swagger_ui(app, config)

@app.get("/")
async def root():
    return {"message": "Hello World"}

Manual Configuration

from fastapi_env_banner import Environment, EnvBannerConfig

# Custom configuration
config = EnvBannerConfig(
    environment=Environment.STAGING,
    enabled=True,
    custom_text="STAGING ENVIRONMENT",
    custom_color="#FF6B6B",
    position="top",  # or "bottom"
    show_in_swagger=True
)

Supported Environments

The library supports the following environments with pre-defined colors:

Environment	Default Color	Default Text
LOCAL	Green (#4CAF50)	LOCAL ENVIRONMENT
DEVELOPMENT	Blue (#2196F3)	DEVELOPMENT ENVIRONMENT
STAGING	Orange (#FF9800)	STAGING ENVIRONMENT
PRODUCTION	Red (#F44336)	PRODUCTION ENVIRONMENT
TESTING	Purple (#9C27B0)	TESTING ENVIRONMENT

Detailed Configuration

Using Environment Variables

Set the ENVIRONMENT variable (or another of your choice):

export ENVIRONMENT=staging

Accepted values:

• local
• dev, development
• stage, staging
• prod, production
• test, testing

Configuration Parameters

EnvBannerConfig(
    environment: Environment = Environment.LOCAL,
    enabled: bool = True,
    custom_text: Optional[str] = None,
    custom_color: Optional[str] = None,
    position: str = "top",  # "top" or "bottom"
    show_in_swagger: bool = True
)

Examples

Example 1: Minimal Configuration

from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware

app = FastAPI()
app.add_middleware(EnvBannerMiddleware, config=EnvBannerConfig.from_env())

Example 2: Full Customization

from fastapi import FastAPI
from fastapi_env_banner import (
    Environment,
    EnvBannerConfig,
    EnvBannerMiddleware,
    setup_swagger_ui
)

app = FastAPI(title="Production API")

config = EnvBannerConfig(
    environment=Environment.STAGING,
    custom_text="⚠️ TEST ENVIRONMENT - DO NOT USE IN PRODUCTION ⚠️",
    custom_color="#E91E63",
    position="bottom",
    show_in_swagger=True
)

app.add_middleware(EnvBannerMiddleware, config=config)
setup_swagger_ui(app, config)

Example 3: Disable in Production

import os
from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware

app = FastAPI()

# Completely disable in production
is_production = os.getenv("ENVIRONMENT") == "production"

config = EnvBannerConfig.from_env()
config.enabled = not is_production

app.add_middleware(EnvBannerMiddleware, config=config)

Security

By default, the banner is NOT displayed in production environment as a security measure. This prevents environment information from being accidentally exposed.

To force display in production (not recommended):

config = EnvBannerConfig(
    environment=Environment.PRODUCTION,
    enabled=True  # Force display
)

How It Works

1. Middleware: Intercepts HTML responses and automatically injects the banner
2. Templates: Clean, pythonic HTML generation using string templates
3. Swagger UI: Customizes the documentation page to include the banner
4. Zero Impact: Does not affect JSON APIs or other non-HTML responses
5. Performance: Minimal overhead, only processes HTML responses

Contributing

Contributions are welcome! Feel free to:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

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

Acknowledgments

• Inspired by django-env-notice
• Built with FastAPI
• Developed by PinnLabs

Support

If you encounter any issues or have suggestions, please open an issue.

---

Made with ❤️ by PinnLabs