syneto-openapi-themes 0.2.0

Syneto-branded themes and utilities for OpenAPI documentation tools

Syneto OpenAPI Themes

Syneto-branded themes and utilities for OpenAPI documentation tools, built on top of OpenAPIPages.

Features

• 🎨 Syneto Branding - Official Syneto colors, fonts, and styling
• 🚀 Multiple Documentation Tools - Support for RapiDoc, SwaggerUI, ReDoc, Elements, and Scalar
• 🔧 Easy Integration - Drop-in replacement for custom documentation implementations
• 🎯 FastAPI Ready - Seamless integration with FastAPI applications
• 📱 Responsive Design - Mobile-friendly documentation interfaces
• 🔐 Authentication Support - Built-in JWT and API key authentication handling
• ⚡ Zero Dependencies - Lightweight with minimal dependencies

Installation

pip install syneto-openapi-themes

For FastAPI integration:

pip install syneto-openapi-themes[fastapi]

For all features:

pip install syneto-openapi-themes[all]

Quick Start

Basic Usage

from fastapi import FastAPI
from syneto_openapi_themes import add_syneto_rapidoc

app = FastAPI(title="My API")

# Add Syneto-branded RapiDoc
add_syneto_rapidoc(app, docs_url="/docs")

Custom Branding

from syneto_openapi_themes import (
    SynetoBrandConfig, 
    SynetoTheme, 
    add_syneto_rapidoc
)

# Custom brand configuration
brand_config = SynetoBrandConfig(
    theme=SynetoTheme.LIGHT,
    company_name="My Company",
    logo_url="/static/my-logo.svg"
)

add_syneto_rapidoc(app, brand_config=brand_config)

Multiple Documentation Tools

from syneto_openapi_themes import add_all_syneto_docs

# Add all documentation tools
add_all_syneto_docs(
    app,
    rapidoc_url="/docs",
    swagger_url="/swagger", 
    redoc_url="/redoc",
    elements_url="/elements",
    scalar_url="/scalar"
)

Using the Docs Manager (Recommended)

from syneto_openapi_themes import SynetoDocsManager

# Create docs manager
docs_manager = SynetoDocsManager(app)

# Add all documentation tools with index page
docs_manager.add_all().add_docs_index("/documentation")

# Or add specific tools
docs_manager.add_rapidoc("/docs").add_swagger("/swagger")

Documentation Tools

RapiDoc

Modern, responsive API documentation with interactive features.

from syneto_openapi_themes import SynetoRapiDoc

rapidoc = SynetoRapiDoc(
    openapi_url="/openapi.json",
    title="API Documentation"
)

SwaggerUI

The classic Swagger interface with Syneto theming.

from syneto_openapi_themes import SynetoSwaggerUI

swagger = SynetoSwaggerUI(
    openapi_url="/openapi.json",
    title="API Documentation"
)

ReDoc

Clean, three-panel API documentation.

from syneto_openapi_themes import SynetoReDoc

redoc = SynetoReDoc(
    openapi_url="/openapi.json", 
    title="API Documentation"
)

Elements

Modern API documentation by Stoplight.

from syneto_openapi_themes import SynetoElements

elements = SynetoElements(
    openapi_url="/openapi.json",
    title="API Documentation"
)

Scalar

Beautiful, interactive API documentation.

from syneto_openapi_themes import SynetoScalar

scalar = SynetoScalar(
    openapi_url="/openapi.json",
    title="API Documentation"
)

Brand Configuration

Default Syneto Theme

from syneto_openapi_themes import SynetoBrandConfig

# Default dark theme
config = SynetoBrandConfig()

# Light theme
config = SynetoBrandConfig(theme=SynetoTheme.LIGHT)

Custom Configuration

config = SynetoBrandConfig(
    # Branding
    company_name="My Company",
    logo_url="/static/logo.svg",
    favicon_url="/static/favicon.ico",
    
    # Theme
    theme=SynetoTheme.DARK,
    primary_color="#ad0f6c",
    background_color="#07080d",
    
    # Typography
    regular_font="'Inter', sans-serif",
    mono_font="'JetBrains Mono', monospace",
    
    # Custom assets
    custom_css_urls=["/static/custom.css"],
    custom_js_urls=["/static/custom.js"]
)

Logo Customization

NEW: Syneto OpenAPI Themes now includes the official Syneto logo by default! No configuration needed for Syneto projects.

from syneto_openapi_themes import add_syneto_rapidoc

# Default configuration automatically includes the official Syneto logo
add_syneto_rapidoc(app, docs_url="/docs")

You can still customize the logo with either external URLs or inline SVG content:

Using Logo URLs

from syneto_openapi_themes import get_brand_config_with_custom_logo

# Use a local logo file
config = get_brand_config_with_custom_logo("/static/my-company-logo.svg")

# Use an external logo URL
config = get_brand_config_with_custom_logo("https://example.com/logo.svg")

# Combine with other customizations
config = get_brand_config_with_custom_logo(
    "/static/my-logo.svg",
    theme=SynetoTheme.LIGHT,
    company_name="My Company",
    primary_color="#ff0000"
)

Using Inline SVG Content (Recommended)

For better performance and reliability, you can embed SVG content directly:

from syneto_openapi_themes import get_brand_config_with_svg_logo, SYNETO_LOGO_SVG

# Option 1: Use your own custom SVG
custom_svg = '''<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 50">
    <rect width="200" height="50" fill="#ad0f6c"/>
    <text x="100" y="30" text-anchor="middle" fill="white" font-family="Arial" font-size="16">
        My Company
    </text>
</svg>'''

config = get_brand_config_with_svg_logo(custom_svg, company_name="My Company")

# Option 2: Use the official Syneto logo constant explicitly
config = get_brand_config_with_svg_logo(
    SYNETO_LOGO_SVG,  # Official Syneto logo (same as default)
    company_name="Syneto"
)

# Combine with other customizations
config = get_brand_config_with_svg_logo(
    custom_svg,
    theme=SynetoTheme.LIGHT,
    company_name="My Company",
    primary_color="#ff0000"
)

# Use with any documentation tool
add_syneto_rapidoc(app, brand_config=config)

Manual Configuration

from syneto_openapi_themes import SynetoBrandConfig, svg_to_data_uri

# Convert SVG to data URI manually
svg_content = '''<svg>...</svg>'''
data_uri = svg_to_data_uri(svg_content)

# Use in brand config
config = SynetoBrandConfig(
    logo_svg=svg_content,  # Inline SVG takes precedence
    logo_url="/fallback/logo.svg",  # Fallback URL
    company_name="My Company"
)

Custom Header Slot (Advanced)

For complete control over the header appearance, you can provide custom HTML content that will be placed in RapiDoc's header slot:

from syneto_openapi_themes import add_syneto_rapidoc

# Custom header with logo and additional elements
custom_header = '''
<div style="display: flex; align-items: center; justify-content: space-between; width: 100%;">
    <div style="display: flex; align-items: center;">
        <img src="/static/logo.svg" alt="My API" style="height: 40px; margin-right: 12px;" />
        <span style="color: #bbb; font-weight: 600; font-size: 18px;">My API Documentation</span>
    </div>
    <div style="display: flex; align-items: center; gap: 16px;">
        <span style="color: #999; font-size: 14px;">v1.0.0</span>
        <a href="/health" style="color: #ff53a8; text-decoration: none;">Health Check</a>
    </div>
</div>
'''

add_syneto_rapidoc(
    app,
    docs_url="/docs",
    header_slot_content=custom_header
)

Header Slot Benefits:

• Complete Control: Full control over header layout and content
• Interactive Elements: Can include buttons, dropdowns, links, etc.
• Proper Positioning: Content appears in the RapiDoc header, not below it
• Responsive Design: Your CSS controls the responsive behavior
• JavaScript Support: Can include interactive JavaScript functionality

Logo Requirements:

• Format: SVG recommended for best scaling and quality
• Size: Optimal dimensions are approximately 120x32 pixels
• Colors: Should work well on dark backgrounds (default theme)
• Accessibility: Include proper alt text and contrast ratios
• Built-in Logo Benefits: Zero configuration for Syneto projects, consistent branding
• Inline SVG Benefits: No external requests, better performance, works offline
• Still Customizable: Easy to override when needed

Available Colors

from syneto_openapi_themes import SynetoColors

# Primary colors
SynetoColors.PRIMARY_MAGENTA  # #ad0f6c
SynetoColors.PRIMARY_DARK     # #07080d  
SynetoColors.PRIMARY_LIGHT    # #fcfdfe

# Accent colors
SynetoColors.ACCENT_RED       # #f01932
SynetoColors.ACCENT_BLUE      # #1e3a8a
SynetoColors.ACCENT_GREEN     # #059669
SynetoColors.ACCENT_YELLOW    # #d97706

# Neutral colors (100-900 scale)
SynetoColors.NEUTRAL_100      # #f8fafc
# ... through to ...
SynetoColors.NEUTRAL_900      # #0f172a

Advanced Usage

Authentication Configuration

# JWT Authentication
rapidoc = SynetoRapiDoc(openapi_url="/openapi.json")
rapidoc.with_jwt_auth(jwt_url="/auth/token")

# API Key Authentication  
rapidoc.with_api_key_auth(api_key_name="X-API-Key")

Custom CSS and JavaScript

config = SynetoBrandConfig(
    custom_css_urls=[
        "/static/custom-theme.css",
        "https://fonts.googleapis.com/css2?family=Custom+Font"
    ],
    custom_js_urls=[
        "/static/analytics.js",
        "/static/custom-behavior.js"
    ]
)

Framework Agnostic Usage

from syneto_openapi_themes import SynetoRapiDoc

# Generate HTML for any framework
rapidoc = SynetoRapiDoc(openapi_url="/openapi.json")
html_content = rapidoc.render()

# Use with Flask, Django, etc.
@app.route('/docs')
def docs():
    return html_content

Migration from Custom Implementation

If you're migrating from a custom RapiDoc implementation:

Before (Custom Implementation)

@app.get("/docs", response_class=HTMLResponse)
def custom_rapidoc_html():
    return custom_template_with_syneto_branding()

After (Syneto OpenAPI Themes)

from syneto_openapi_themes import add_syneto_rapidoc

add_syneto_rapidoc(app, docs_url="/docs")

Development

Setup

git clone <repository-url>
cd syneto-openapi-themes
poetry install

Testing

poetry run pytest

Code Quality

poetry run black .
poetry run ruff check .
poetry run mypy .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run quality checks
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Built on top of OpenAPIPages by Hasan Sezer Tasan.