quas-docs 0.0.3__py3-none-any.whl

quas_docs/__init__.py

@@ -0,0 +1,32 @@
+"""
+Flask OpenAPI Documentation Package
+
+A reusable package for generating comprehensive OpenAPI documentation 
+with Flask-Pydantic-Spec, featuring custom metadata, security schemes,
+and flexible configuration.
+
+Author: Emmanuel Olowu
+License: MIT
+"""
+
+from .core import FlaskOpenAPISpec, SecurityScheme, QueryParameter
+from .config import DocsConfig, ContactInfo, SecuritySchemeConfig
+
+__version__ = "0.0.3"
+__author__ = "Emmanuel Olowu"
+
+# Create a default instance for endpoint decorator export
+_default_spec = FlaskOpenAPISpec(DocsConfig.create_default())
+endpoint = _default_spec.endpoint
+
+# Public API
+__all__ = [
+    "FlaskOpenAPISpec",
+    "SecurityScheme",
+    "QueryParameter",
+    "endpoint",
+    "DocsConfig",
+    "ContactInfo",
+    "SecuritySchemeConfig",
+]
+

quas_docs/config.py

@@ -0,0 +1,246 @@
+"""
+Configuration system for Flask OpenAPI Documentation Package.
+
+This module provides a flexible configuration system that allows easy
+customization of API documentation metadata, security schemes, and behavior.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ContactInfo:
+    """Contact information for the API documentation."""
+    email: Optional[str] = None
+    name: Optional[str] = None
+    url: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for OpenAPI spec."""
+        return {k: v for k, v in {
+            'email': self.email,
+            'name': self.name,
+            'url': self.url
+        }.items() if v is not None}
+
+
+@dataclass
+class SecuritySchemeConfig:
+    """Configuration for a security scheme."""
+    name: str
+    scheme_type: str = "apiKey"
+    location: str = "header"  # header, query, cookie
+    parameter_name: str = "Authorization"
+    description: Optional[str] = None
+    
+    def to_openapi_dict(self) -> Dict[str, Any]:
+        """Convert to OpenAPI security scheme format."""
+        scheme = {
+            'type': self.scheme_type,
+            'in': self.location,
+            'name': self.parameter_name,
+        }
+        if self.description:
+            scheme['description'] = self.description
+        return scheme
+
+
+@dataclass
+class DocsConfig:
+    """Main configuration class for Flask OpenAPI documentation."""
+    
+    # Basic API Information
+    title: str = "Flask API"
+    version: str = "0.0.1"
+    description: Optional[str] = None
+    terms_of_service: Optional[str] = None
+    
+    # Contact Information
+    contact: Optional[ContactInfo] = None
+    
+    # License Information
+    license_name: Optional[str] = None
+    license_url: Optional[str] = None
+    
+    # Server Information
+    servers: List[Dict[str, str]] = field(default_factory=list)
+    
+    # Security Schemes
+    security_schemes: Dict[str, SecuritySchemeConfig] = field(default_factory=dict)
+    
+    # Customization Options
+    preserve_flask_routes: bool = True  # Keep <string:param> format
+    clear_auto_discovered: bool = True  # Remove auto-discovered duplicates
+    add_default_responses: bool = True  # Add default response schemas
+    
+    # External Documentation
+    external_docs_url: Optional[str] = None
+    external_docs_description: Optional[str] = None
+    
+    @classmethod
+    def create_default(cls) -> 'DocsConfig':
+        """Create a default configuration with common settings."""
+        return cls(
+            title="Flask API",
+            version="0.0.1",
+            description="API documentation generated with Flask OpenAPI Docs",
+            contact=ContactInfo(
+                email="api@example.com",
+                name="API Team"
+            ),
+            security_schemes={
+                "BearerAuth": SecuritySchemeConfig(
+                    name="BearerAuth",
+                    description="JWT Bearer token authentication"
+                )
+            }
+        )
+    
+    @classmethod
+    def from_env(cls, prefix: str = "API_") -> 'DocsConfig':
+        """Create configuration from environment variables with optional prefix.
+        
+        Args:
+            prefix: Environment variable prefix (default: 'API_')
+            
+        Environment Variables:
+            {prefix}TITLE: API title
+            {prefix}VERSION: API version
+            {prefix}DESCRIPTION: API description
+            {prefix}CONTACT_EMAIL: Contact email
+            {prefix}CONTACT_NAME: Contact name
+            {prefix}CONTACT_URL: Contact URL
+            {prefix}LICENSE_NAME: License name
+            {prefix}LICENSE_URL: License URL
+            {prefix}PRESERVE_FLASK_ROUTES: Keep Flask route format (true/false)
+        """
+        import os
+        
+        # Helper function to get bool from env
+        def get_bool(key: str, default: bool) -> bool:
+            value = os.getenv(key, str(default)).lower()
+            return value in ('true', '1', 'yes', 'on')
+        
+        # Create contact info if any contact env vars are present
+        contact = None
+        contact_email = os.getenv(f"{prefix}CONTACT_EMAIL")
+        contact_name = os.getenv(f"{prefix}CONTACT_NAME")
+        contact_url = os.getenv(f"{prefix}CONTACT_URL")
+        
+        if any([contact_email, contact_name, contact_url]):
+            contact = ContactInfo(
+                email=contact_email,
+                name=contact_name,
+                url=contact_url
+            )
+        
+        return cls(
+            title=os.getenv(f"{prefix}TITLE", "Flask API"),
+            version=os.getenv(f"{prefix}VERSION", "0.0.1"),
+            description=os.getenv(f"{prefix}DESCRIPTION"),
+            contact=contact,
+            license_name=os.getenv(f"{prefix}LICENSE_NAME"),
+            license_url=os.getenv(f"{prefix}LICENSE_URL"),
+            preserve_flask_routes=get_bool(f"{prefix}PRESERVE_FLASK_ROUTES", True),
+            clear_auto_discovered=get_bool(f"{prefix}CLEAR_AUTO_DISCOVERED", True),
+            add_default_responses=get_bool(f"{prefix}ADD_DEFAULT_RESPONSES", True)
+        )
+    
+    @classmethod
+    def from_dict(cls, config_dict: Dict[str, Any]) -> 'DocsConfig':
+        """Create configuration from a dictionary.
+        
+        Args:
+            config_dict: Dictionary containing configuration values
+            
+        Example:
+            config = DocsConfig.from_dict({
+                'title': 'My API',
+                'version': '2.0.0',
+                'contact': {'email': 'dev@example.com', 'name': 'Dev Team'},
+                'security_schemes': {
+                    'BearerAuth': {'description': 'JWT authentication'}
+                }
+            })
+        """
+        # Extract contact info if present
+        contact = None
+        if 'contact' in config_dict:
+            contact_data = config_dict['contact']
+            if isinstance(contact_data, dict):
+                contact = ContactInfo(**contact_data)
+        
+        # Extract security schemes if present
+        security_schemes = {}
+        if 'security_schemes' in config_dict:
+            schemes_data = config_dict['security_schemes']
+            if isinstance(schemes_data, dict):
+                for name, scheme_data in schemes_data.items():
+                    if isinstance(scheme_data, dict):
+                        security_schemes[name] = SecuritySchemeConfig(name=name, **scheme_data)
+        
+        # Create the config with known fields
+        known_fields = {
+            'title', 'version', 'description', 'terms_of_service', 
+            'license_name', 'license_url', 'servers', 'preserve_flask_routes',
+            'clear_auto_discovered', 'add_default_responses', 
+            'external_docs_url', 'external_docs_description'
+        }
+        
+        filtered_dict = {k: v for k, v in config_dict.items() if k in known_fields}
+        
+        return cls(
+            contact=contact,
+            security_schemes=security_schemes,
+            **filtered_dict
+        )
+    
+    def add_security_scheme(self, name: str, config: SecuritySchemeConfig) -> None:
+        """Add a new security scheme to the configuration."""
+        self.security_schemes[name] = config
+    
+    def add_server(self, url: str, description: str = "") -> None:
+        """Add a server to the configuration."""
+        self.servers.append({"url": url, "description": description})
+    
+    def to_openapi_info(self) -> Dict[str, Any]:
+        """Convert to OpenAPI info object."""
+        info: Dict[str, Any] = {
+            "title": self.title,
+            "version": self.version
+        }
+        
+        if self.description:
+            info["description"] = self.description
+        if self.terms_of_service:
+            info["termsOfService"] = self.terms_of_service
+        if self.contact:
+            contact_dict = self.contact.to_dict()
+            if contact_dict:
+                info["contact"] = contact_dict
+        if self.license_name:
+            license_info: Dict[str, Any] = {"name": self.license_name}
+            if self.license_url:
+                license_info["url"] = self.license_url
+            info["license"] = license_info
+        
+        return info
+    
+    def to_openapi_security_schemes(self) -> Dict[str, Dict[str, Any]]:
+        """Convert security schemes to OpenAPI format."""
+        return {
+            name: config.to_openapi_dict() 
+            for name, config in self.security_schemes.items()
+        }
+    
+    def to_openapi_external_docs(self) -> Optional[Dict[str, Any]]:
+        """Convert external docs to OpenAPI format."""
+        if self.external_docs_url:
+            docs: Dict[str, Any] = {"url": self.external_docs_url}
+            if self.external_docs_description:
+                docs["description"] = self.external_docs_description
+            return docs
+        return None

quas_docs/core.py

@@ -0,0 +1,483 @@
+"""
+Core functionality for Flask OpenAPI Documentation Package.
+
+This module contains the main FlaskOpenAPISpec class and supporting utilities
+for generating comprehensive OpenAPI documentation with custom metadata.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Type, Tuple
+
+from flask import Flask
+from flask_pydantic_spec import FlaskPydanticSpec
+from pydantic import BaseModel
+
+from .config import DocsConfig
+
+
+class SecurityScheme(str, Enum):
+    """Available security schemes for API endpoints."""
+    PUBLIC_BEARER = "PublicBearerAuth"
+    ADMIN_BEARER = "AdminBearerAuth"
+    BEARER_AUTH = "BearerAuth"
+    NONE = "none"
+
+
+class QueryParameter:
+    """Represents a query parameter definition."""
+    def __init__(
+        self,
+        name: str,
+        type_: str = "string",
+        required: bool = False,
+        description: Optional[str] = None,
+        default: Any = None
+    ):
+        self.name = name
+        self.type_ = type_
+        self.required = required
+        self.description = description or f"The {name} parameter"
+        self.default = default
+
+
+class EndpointMetadata:
+    """Container for all endpoint metadata including request body, security, etc."""
+
+    def __init__(
+        self,
+        request_body: Optional[Type[BaseModel]] = None,
+        security: Optional[SecurityScheme] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        deprecated: bool = False,
+        query_params: Optional[List[QueryParameter]] = None,
+        responses: Optional[Dict[Any, Any]] = None,
+        **extra_metadata: Any
+    ):
+        self.request_body = request_body
+        self.security = security
+        self.tags = tags or []
+        self.summary = summary
+        self.description = description
+        self.deprecated = deprecated
+        self.query_params = query_params or []
+        self.responses: Dict[Any, Any] = responses or {}
+        self.extra_metadata = extra_metadata
+
+
+class FlaskOpenAPISpec:
+    """
+    Main class for Flask OpenAPI documentation generation.
+    
+    Provides a clean, configurable interface for generating comprehensive
+    OpenAPI documentation with custom metadata, security schemes, and
+    flexible configuration options.
+    """
+    
+    def __init__(self, config: Optional[DocsConfig] = None):
+        """
+        Initialize the OpenAPI spec generator.
+        
+        Args:
+            config: Configuration object. If None, creates default config.
+        """
+        self.config = config or DocsConfig.create_default()
+        self.spec = FlaskPydanticSpec(
+            'flask', 
+            title=self.config.title, 
+            version=self.config.version
+        )
+        self._registered_endpoints: List[Tuple[str, str, EndpointMetadata]] = []
+    
+    def init_app(self, app: Flask) -> None:
+        """
+        Initialize the OpenAPI documentation for a Flask application.
+        
+        Args:
+            app: The Flask application instance to configure
+        """
+        # Extract our custom endpoints before registering the spec
+        self._extract_decorated_endpoints(app)
+        
+        # Register the spec with the app
+        self.spec.register(app)
+        
+        # Access the underlying OpenAPI spec object
+        inner: Any = getattr(self.spec, 'spec', None)
+        if inner is None:
+            return
+        
+        # Clear auto-discovered paths to prevent duplicates if configured
+        if self.config.clear_auto_discovered and isinstance(inner, dict) and 'paths' in inner:
+            inner['paths'] = {}
+        
+        # Apply our customizations after spec registration
+        self._setup_security_schemes(inner)
+        self._setup_info_metadata(inner)
+        self._setup_servers(inner)
+        self._setup_external_docs(inner)
+        
+        # Apply our custom endpoint metadata
+        self._apply_registered_endpoints(inner)
+    
+    def endpoint(
+        self,
+        request_body: Optional[Type[BaseModel]] = None,
+        security: Optional[SecurityScheme] = None,
+        tags: Optional[List[str]] = None,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        deprecated: bool = False,
+        query_params: Optional[List[QueryParameter]] = None,
+        responses: Optional[Dict[Any, Any]] = None,
+        **extra_metadata: Any
+    ) -> Callable:
+        """
+        Unified decorator for comprehensive endpoint documentation.
+        
+        Args:
+            request_body: Pydantic model class for request body validation/documentation
+            security: Security scheme required for this endpoint
+            tags: List of tags for grouping endpoints in documentation
+            summary: Brief summary of the endpoint functionality
+            description: Detailed description of the endpoint
+            deprecated: Whether this endpoint is deprecated
+            responses: Mapping of status codes to Pydantic models or OpenAPI schema dicts
+            **extra_metadata: Additional metadata for future extensibility
+            
+        Returns:
+            Decorator function that preserves the original view function behavior
+        """
+        def decorator(func: Callable) -> Callable:
+            # Create metadata object
+            metadata = EndpointMetadata(
+                request_body=request_body,
+                security=security,
+                tags=tags,
+                summary=summary,
+                description=description,
+                deprecated=deprecated,
+                query_params=query_params,
+                responses=responses,
+                **extra_metadata
+            )
+            
+            # Attach metadata to function for later discovery
+            func._endpoint_metadata = metadata  # type: ignore
+            
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+            
+            # Ensure metadata is also attached to the wrapper
+            wrapper._endpoint_metadata = metadata  # type: ignore
+            return wrapper
+        return decorator
+    
+
+    
+    def _extract_decorated_endpoints(self, app: Flask) -> None:
+        """Extract endpoint metadata from decorated view functions."""
+        try:
+            for rule in app.url_map.iter_rules():
+                endpoint = rule.endpoint
+                view_func = app.view_functions.get(endpoint)
+                
+                if not view_func:
+                    continue
+                
+                metadata = None
+                
+                # Check for endpoint metadata
+                if hasattr(view_func, '_endpoint_metadata'):
+                    metadata = view_func._endpoint_metadata
+                
+                if metadata:
+                    # Extract valid HTTP methods (exclude HEAD, OPTIONS)
+                    methods = [m.lower() for m in rule.methods or set() 
+                              if m.lower() not in ('head', 'options')]
+                    
+                    if not methods:
+                        continue
+                    
+                    # Use the first valid method for documentation
+                    method = methods[0]
+                    
+                    # Handle path format based on configuration
+                    path = rule.rule
+                    if not self.config.preserve_flask_routes:
+                        # Convert Flask route format to OpenAPI format
+                        # <string:param> -> {param}, <int:param> -> {param}, etc.
+                        path = re.sub(r'<(?:\w+:)?(\w+)>', r'{\1}', path)
+                    
+                    # Try to extract response schemas from @spec.validate decorator
+                    try:
+                        if hasattr(view_func, '_spec_responses'):
+                            responses = getattr(view_func, '_spec_responses', {})
+                            norm_responses = self._normalize_spec_responses(responses)
+                            if norm_responses:
+                                metadata.responses.update(norm_responses)
+                    except Exception:
+                        pass
+                    
+                    self._registered_endpoints.append((path, method, metadata))
+        except Exception:
+            # Silently continue - documentation generation should never break the app
+            pass
+    
+    def _normalize_spec_responses(self, raw_responses: Any) -> Dict[str, Any]:
+        """Normalize flask-pydantic-spec response mapping into OpenAPI-ready dict."""
+        normalized: Dict[str, Any] = {}
+        if isinstance(raw_responses, dict):
+            for key, val in raw_responses.items():
+                code_str = str(key)
+                if code_str.upper().startswith("HTTP_"):
+                    code_str = code_str.split("HTTP_", 1)[1]
+                normalized[code_str] = val
+        return normalized
+    
+    def _setup_security_schemes(self, inner: Any) -> None:
+        """Configure security schemes from config."""
+        security_schemes = self.config.to_openapi_security_schemes()
+        
+        if not security_schemes:
+            return
+        
+        try:
+            # Try flask-pydantic-spec's component interface first
+            comps: Any = getattr(inner, 'components', None)
+            if comps is not None and hasattr(comps, 'security_scheme'):
+                for scheme_name, scheme_config in security_schemes.items():
+                    getattr(comps, 'security_scheme')(scheme_name, scheme_config)
+            # Fallback to direct dictionary manipulation
+            elif isinstance(inner, dict):
+                comp_dict = inner.setdefault('components', {})
+                schemes = comp_dict.setdefault('securitySchemes', {})
+                schemes.update(security_schemes)
+        except Exception:
+            # Silently fail to avoid breaking app initialization
+            pass
+    
+    def _setup_info_metadata(self, inner: Any) -> None:
+        """Configure API metadata from config."""
+        info_data = self.config.to_openapi_info()
+        
+        try:
+            # Attempt to access info object directly
+            info_dict = getattr(inner, '_info', None)
+            target = (info_dict if isinstance(info_dict, dict) 
+                     else inner.setdefault('info', {}) if isinstance(inner, dict) 
+                     else None)
+            
+            if target is not None:
+                target.update(info_data)
+        except Exception:
+            # Silently fail to avoid breaking app initialization
+            pass
+    
+    def _setup_servers(self, inner: Any) -> None:
+        """Configure servers from config."""
+        if not self.config.servers:
+            return
+        
+        try:
+            if isinstance(inner, dict):
+                inner['servers'] = self.config.servers
+        except Exception:
+            pass
+    
+    def _setup_external_docs(self, inner: Any) -> None:
+        """Configure external documentation from config."""
+        external_docs = self.config.to_openapi_external_docs()
+        if not external_docs:
+            return
+        
+        try:
+            if isinstance(inner, dict):
+                inner['externalDocs'] = external_docs
+        except Exception:
+            pass
+    
+    def _apply_registered_endpoints(self, inner: Any) -> None:
+        """Apply all endpoint metadata to OpenAPI spec."""
+        if not self._registered_endpoints:
+            return
+
+        # Collect unique models for schema registration
+        models_to_register = set()
+        for _, _, metadata in self._registered_endpoints:
+            if metadata.request_body:
+                models_to_register.add(metadata.request_body)
+            for resp_model in metadata.responses.values():
+                if hasattr(resp_model, "model_json_schema"):
+                    models_to_register.add(resp_model)
+
+        # Register Pydantic model schemas in components/schemas section
+        if models_to_register:
+            try:
+                comps: Any = getattr(inner, 'components', None)
+                if comps is not None and hasattr(comps, 'schema'):
+                    # Use flask-pydantic-spec's schema registration method
+                    for model in models_to_register:
+                        comps.schema(model.__name__, model.model_json_schema())
+                elif isinstance(inner, dict):
+                    # Direct dictionary manipulation fallback
+                    schemas = inner.setdefault('components', {}).setdefault('schemas', {})
+                    for model in models_to_register:
+                        schemas[model.__name__] = model.model_json_schema()
+            except Exception:
+                # Continue even if schema registration fails
+                pass
+
+        # Apply all metadata to each registered endpoint
+        for path, method, metadata in self._registered_endpoints:
+            operation_spec = {}
+            
+            # Initialize parameters list
+            operation_spec['parameters'] = []
+
+            # Extract path parameters and add them to the spec
+            import re
+            path_params = re.findall(r'\{(\w+)\}', path)
+            for param_name in path_params:
+                operation_spec['parameters'].append({
+                    'name': param_name,
+                    'in': 'path',
+                    'required': True,
+                    'schema': {'type': 'string'},
+                    'description': f'The {param_name} parameter'
+                })
+
+            # Add query parameters from metadata
+            for query_param in metadata.query_params:
+                operation_spec['parameters'].append({
+                    'name': query_param.name,
+                    'in': 'query',
+                    'required': query_param.required,
+                    'schema': {'type': query_param.type_},
+                    'description': query_param.description,
+                    **({'default': query_param.default} if query_param.default is not None else {})
+                })
+            
+            # Add request body if specified
+            if metadata.request_body:
+                operation_spec['requestBody'] = {
+                    'required': True,
+                    'content': {
+                        'application/json': {
+                            'schema': {'$ref': f"#/components/schemas/{metadata.request_body.__name__}"}
+                        }
+                    }
+                }
+            
+            # Add security requirements if specified
+            if metadata.security and metadata.security != SecurityScheme.NONE:
+                operation_spec['security'] = [{metadata.security.value: []}]
+            
+            # Add tags, summary, description, etc.
+            if metadata.tags:
+                operation_spec['tags'] = metadata.tags
+            if metadata.summary:
+                operation_spec['summary'] = metadata.summary
+            if metadata.description:
+                operation_spec['description'] = metadata.description
+            if metadata.deprecated:
+                operation_spec['deprecated'] = True
+            
+            # Add responses from decorator or normalized @spec.validate
+            if metadata.responses:
+                op_responses: Dict[str, Any] = {}
+                for code, model in metadata.responses.items():
+                    code_str = str(code)
+                    if code_str.upper().startswith("HTTP_"):
+                        code_str = code_str.split("HTTP_", 1)[1]
+                    if hasattr(model, "model_json_schema"):
+                        op_responses[code_str] = {
+                            "description": "Response",
+                            "content": {
+                                "application/json": {
+                                    "schema": {"$ref": f"#/components/schemas/{model.__name__}"}
+                                }
+                            }
+                        }
+                    elif isinstance(model, dict):
+                        op_responses[code_str] = {
+                            "description": "Response",
+                            "content": {
+                                "application/json": {"schema": model}
+                            }
+                        }
+                    else:
+                        op_responses[code_str] = {"description": "Response"}
+                if op_responses:
+                    operation_spec['responses'] = op_responses
+            
+            # Add any extra metadata
+            operation_spec.update(metadata.extra_metadata)
+            
+            # Apply the operation spec to the OpenAPI spec
+            if operation_spec:
+                # Direct dictionary manipulation for reliable metadata application
+                if isinstance(inner, dict):
+                    # Get or create the path and method
+                    if path not in inner.setdefault('paths', {}):
+                        inner['paths'][path] = {}
+                    if method not in inner['paths'][path]:
+                        inner['paths'][path][method] = {}
+                    
+                    ops = inner['paths'][path][method]
+                    
+                    # Apply our custom metadata (this will override defaults)
+                    for key, value in operation_spec.items():
+                        if key == 'responses' and 'responses' in ops:
+                            # Merge responses instead of overwriting
+                            ops['responses'].update(value)
+                        else:
+                            ops[key] = value
+                    
+                    # Add default response schemas if configured and not already present
+                    if self.config.add_default_responses:
+                        if 'responses' not in ops:
+                            ops['responses'] = {}
+                        
+                        if '200' not in ops['responses']:
+                            ops['responses']['200'] = {
+                                'description': 'Success',
+                                'content': {
+                                    'application/json': {
+                                        'schema': {
+                                            'type': 'object',
+                                            'properties': {
+                                                'status': {'type': 'string', 'enum': ['success']},
+                                                'status_code': {'type': 'integer'},
+                                                'message': {'type': 'string'},
+                                                'data': {'type': 'object'}
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        if '400' not in ops['responses']:
+                            ops['responses']['400'] = {
+                                'description': 'Bad Request',
+                                'content': {
+                                    'application/json': {
+                                        'schema': {
+                                            'type': 'object',
+                                            'properties': {
+                                                'status': {'type': 'string', 'enum': ['failed']},
+                                                'status_code': {'type': 'integer'},
+                                                'message': {'type': 'string'},
+                                                'data': {'type': 'object'}
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+
+

quas_docs-0.0.3.dist-info/METADATA

@@ -0,0 +1,493 @@
+Metadata-Version: 2.4
+Name: quas-docs
+Version: 0.0.3
+Summary: A powerful, reusable package for generating comprehensive OpenAPI documentation with Flask-Pydantic-Spec
+Home-page: https://github.com/zeddyemy/flask-openapi-docs
+Author: Emmanuel Olowu
+Author-email: Emmanuel Olowu <zeddyemy@gmail.com>
+License: MIT
+Keywords: flask,openapi,swagger,documentation,api,pydantic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Flask
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: flask-pydantic-spec>=0.8.6
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# Flask OpenAPI Documentation Package
+
+A powerful, reusable package for generating comprehensive OpenAPI documentation with Flask-Pydantic-Spec. Features custom metadata, security schemes, and flexible configuration options.
+
+## ✨ Features
+
+- **Flexible Configuration**: Easy-to-use configuration system for API metadata
+- **Custom Security Schemes**: Support for multiple authentication types
+- **Tag-based Organization**: Group endpoints by functionality
+- **Route Format Control**: Choose between Flask (`<string:param>`) and OpenAPI (`{param}`) formats
+- **Automatic Schema Registration**: Seamless Pydantic model integration
+- **Backward Compatibility**: Drop-in replacement for existing setups
+- **Zero Dependencies**: Only requires `flask-pydantic-spec` and `pydantic`
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```python
+from flask import Flask
+from quas_docs import FlaskOpenAPISpec, DocsConfig, SecurityScheme, endpoint
+
+# Create configuration
+config = DocsConfig(
+    title="My API",
+    version="0.0.1",
+    description="A sample API with comprehensive documentation",
+    contact=ContactInfo(
+        email="api@example.com",
+        name="API Team"
+    )
+)
+
+# Initialize the spec
+spec = FlaskOpenAPISpec(config)
+
+# Create Flask app
+app = Flask(__name__)
+
+# Add endpoints with metadata
+@app.post("/users")
+@endpoint(
+    request_body=CreateUserRequest,
+    security=SecurityScheme.BEARER_AUTH,
+    tags=["Users"],
+    summary="Create New User",
+    description="Creates a new user account with validation"
+)
+def create_user():
+    return {"message": "User created"}
+
+# Initialize documentation
+spec.init_app(app)
+```
+
+### Dynamic Configuration Methods
+
+```python
+from quas_docs import FlaskOpenAPISpec, DocsConfig
+
+# Method 1: From dictionary (recommended)
+config = DocsConfig.from_dict({
+    'title': 'My API',
+    'version': '2.0.0',
+    'description': 'API built with dynamic configuration',
+    'contact': {
+        'email': 'dev@mycompany.com',
+        'name': 'Development Team',
+        'url': 'https://mycompany.com'
+    },
+    'security_schemes': {
+        'BearerAuth': {'description': 'JWT authentication'},
+        'ApiKeyAuth': {
+            'scheme_type': 'apiKey',
+            'location': 'header',
+            'parameter_name': 'X-API-Key',
+            'description': 'API key authentication'
+        }
+    },
+    'preserve_flask_routes': True
+})
+
+# Method 2: From environment variables
+config = DocsConfig.from_env(prefix="MY_API_")
+
+# Method 3: Create default and customize
+config = DocsConfig.create_default()
+config.title = "Custom API"
+config.version = "2.0.0"
+
+# Method 4: Manual construction
+config = DocsConfig(
+    title="Custom API",
+    version="2.0.0",
+    description="Custom API with specific requirements"
+)
+```
+
+## 📋 Configuration Options
+
+### DocsConfig Class
+
+```python
+@dataclass
+class DocsConfig:
+    # Basic API Information
+    title: str = "Flask API"
+    version: str = "0.0.1"
+    description: Optional[str] = None
+    terms_of_service: Optional[str] = None
+    
+    # Contact Information
+    contact: Optional[ContactInfo] = None
+    
+    # License Information
+    license_name: Optional[str] = None
+    license_url: Optional[str] = None
+    
+    # Server Information
+    servers: List[Dict[str, str]] = field(default_factory=list)
+    
+    # Security Schemes
+    security_schemes: Dict[str, SecuritySchemeConfig] = field(default_factory=dict)
+    
+    # Customization Options
+    preserve_flask_routes: bool = True  # Keep <string:param> format
+    clear_auto_discovered: bool = True  # Remove auto-discovered duplicates
+    add_default_responses: bool = True  # Add default response schemas
+    
+    # External Documentation
+    external_docs_url: Optional[str] = None
+    external_docs_description: Optional[str] = None
+```
+
+### Security Schemes
+
+```python
+from quas_docs import SecuritySchemeConfig
+
+# API Key Authentication
+api_key_config = SecuritySchemeConfig(
+    name="ApiKeyAuth",
+    scheme_type="apiKey",
+    location="header",
+    parameter_name="X-API-Key",
+    description="API key authentication"
+)
+
+# Bearer Token Authentication
+bearer_config = SecuritySchemeConfig(
+    name="BearerAuth",
+    scheme_type="apiKey",
+    location="header", 
+    parameter_name="Authorization",
+    description="JWT Bearer token authentication"
+)
+
+# Add to configuration
+config.add_security_scheme("ApiKeyAuth", api_key_config)
+config.add_security_scheme("BearerAuth", bearer_config)
+```
+
+### Contact Information
+
+```python
+from quas_docs import ContactInfo
+
+contact = ContactInfo(
+    email="api@example.com",
+    name="API Development Team",
+    url="https://example.com/contact"
+)
+
+config.contact = contact
+```
+
+## 🎯 Endpoint Decoration
+
+### The @endpoint Decorator
+
+```python
+@endpoint(
+    request_body=Optional[Type[BaseModel]],      # Pydantic model for request body
+    security=Optional[SecurityScheme],           # Security requirement
+    tags=Optional[List[str]],                    # Organization tags
+    summary=Optional[str],                       # Brief description
+    description=Optional[str],                   # Detailed description
+    query_params=Optional[List[QueryParameter]], # Query parameters for GET endpoints
+    deprecated=bool,                             # Mark as deprecated
+    **extra_metadata                             # Custom metadata
+)
+```
+
+### Examples
+
+```python
+# Basic endpoint with request body
+@app.post("/auth/login")
+@endpoint(
+    request_body=LoginRequest,
+    tags=["Authentication"],
+    summary="User Login",
+    description="Authenticate user with email and password"
+)
+@spec.validate(resp=Response(HTTP_200=ApiResponse))
+def login():
+    return AuthController.login()
+
+# Secured endpoint with query parameters
+@app.get("/users")
+@endpoint(
+    security=SecurityScheme.BEARER_AUTH,
+    tags=["Users"],
+    summary="List Users",
+    description="Get paginated list of users with filtering options",
+    query_params=[
+        QueryParameter("page", "integer", required=False, description="Page number", default=1),
+        QueryParameter("per_page", "integer", required=False, description="Items per page", default=10),
+        QueryParameter("search", "string", required=False, description="Search by name or email"),
+        QueryParameter("active", "boolean", required=False, description="Filter by active status", default=True),
+    ]
+)
+@spec.validate(resp=Response(HTTP_200=UsersListResponse))
+def list_users():
+    return UserController.list()
+
+# Public endpoint with custom metadata
+@app.get("/health")
+@endpoint(
+    tags=["System"],
+    summary="Health Check",
+    description="Check API health status",
+    custom_field="health-check"  # Custom metadata
+)
+def health_check():
+    return {"status": "healthy"}
+```
+
+## 🔧 Advanced Configuration
+
+### Custom Response Schemas
+
+```python
+# The package automatically adds default response schemas
+# You can disable this behavior:
+config.add_default_responses = False
+
+# Custom response schemas are preserved from @spec.validate decorators
+@app.post("/users")
+@endpoint(tags=["Users"])
+@spec.validate(resp=Response(
+    HTTP_201=CreateUserResponse,
+    HTTP_400=ErrorResponse,
+    HTTP_409=ConflictResponse
+))
+def create_user():
+    return UserController.create()
+```
+
+### Route Format Control
+
+```python
+# Keep Flask format: /users/<string:user_id>
+config.preserve_flask_routes = True
+
+# Use OpenAPI format: /users/{user_id}  
+config.preserve_flask_routes = False
+```
+
+### Servers Configuration
+
+```python
+# Add multiple servers
+config.add_server("https://api.example.com", "Production")
+config.add_server("https://staging-api.example.com", "Staging")
+config.add_server("http://localhost:5000", "Development")
+```
+
+### External Documentation
+
+```python
+config.external_docs_url = "https://docs.example.com"
+config.external_docs_description = "Complete API Documentation"
+```
+
+### Environment Variable Configuration
+
+Set environment variables and load them automatically:
+
+```bash
+# .env file or environment
+export API_TITLE="My Project API"
+export API_VERSION="1.2.0"
+export API_DESCRIPTION="API for my awesome project"
+export API_CONTACT_EMAIL="api@myproject.com"
+export API_CONTACT_NAME="API Team"
+export API_CONTACT_URL="https://myproject.com/contact"
+export API_LICENSE_NAME="MIT"
+export API_PRESERVE_FLASK_ROUTES="true"
+```
+
+```python
+# Load configuration from environment
+config = DocsConfig.from_env()  # Uses API_ prefix by default
+
+# Or use custom prefix
+config = DocsConfig.from_env(prefix="MYAPI_")
+```
+
+## 📦 Integration Examples
+
+### Replace Existing Setup
+
+If you have an existing Flask app with manual OpenAPI setup:
+
+```python
+# OLD WAY
+from flask_pydantic_spec import FlaskPydanticSpec
+spec = FlaskPydanticSpec('flask', title='My API', version='0.0.1')
+
+# NEW WAY
+from quas_docs import FlaskOpenAPISpec, DocsConfig
+config = DocsConfig(title='My API', version='0.0.1')
+spec_instance = FlaskOpenAPISpec(config)
+spec = spec_instance.spec  # For backward compatibility
+```
+
+### Multiple APIs
+
+```python
+# API 1: Public API
+public_config = DocsConfig(
+    title="Public API",
+    version="0.0.1",
+    preserve_flask_routes=True
+)
+public_spec = FlaskOpenAPISpec(public_config)
+
+# API 2: Admin API  
+admin_config = DocsConfig(
+    title="Admin API",
+    version="0.0.1",
+    preserve_flask_routes=False
+)
+admin_spec = FlaskOpenAPISpec(admin_config)
+```
+
+### Custom Project Setup
+
+```python
+# projects/my_project/docs_config.py
+from quas_docs import DocsConfig, ContactInfo, SecuritySchemeConfig
+
+def create_my_project_config():
+    config = DocsConfig(
+        title="My Project API",
+        version="2.1.0",
+        description="Custom project with specific requirements",
+        contact=ContactInfo(
+            email="dev@myproject.com",
+            name="Development Team",
+            url="https://myproject.com"
+        )
+    )
+    
+    # Add custom security schemes
+    config.add_security_scheme("ApiKey", SecuritySchemeConfig(
+        name="ApiKey",
+        parameter_name="X-API-Key",
+        description="Project-specific API key"
+    ))
+    
+    config.add_server("https://api.myproject.com", "Production")
+    config.add_server("http://localhost:8000", "Development")
+    
+    return config
+
+# projects/my_project/app.py
+from quas_docs import FlaskOpenAPISpec
+from .docs_config import create_my_project_config
+
+config = create_my_project_config()
+spec = FlaskOpenAPISpec(config)
+```
+
+## 🔄 Migration Guide
+
+### From Manual Setup
+
+1. **Copy the docs/ folder** to your project
+2. **Replace your existing docs setup**:
+   ```python
+   # Replace your old setup with:
+   from quas_docs import FlaskOpenAPISpec, DocsConfig, endpoint, SecurityScheme
+   
+   config = DocsConfig.from_dict({
+       'title': 'Your API Name',
+       'version': '0.0.1',
+       # ... your settings
+   })
+   spec_instance = FlaskOpenAPISpec(config)
+   spec = spec_instance.spec  # For @spec.validate decorators
+   ```
+3. **Use the @endpoint decorator**:
+   ```python
+   @endpoint(
+       request_body=YourModel,
+       security=SecurityScheme.BEARER_AUTH,
+       tags=["Your Tag"],
+       summary="Your Summary"
+   )
+   ```
+4. **Initialize documentation**:
+   ```python
+   spec_instance.init_app(app)
+   ```
+
+### Clean v1.0 Design
+
+The package follows a clean, modern approach:
+
+- Single `@endpoint` decorator for all metadata
+- Configuration-driven setup
+- No legacy compatibility code
+- Streamlined API surface
+
+## 📝 Best Practices
+
+1. **Use meaningful tags** to organize endpoints logically
+2. **Provide clear summaries and descriptions** for better developer experience
+3. **Configure contact information** for API support
+4. **Use appropriate security schemes** for different endpoint types
+5. **Test documentation** in both Swagger UI and Redoc
+6. **Version your APIs** properly using semantic versioning
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue**: Endpoints appear in "default" category
+**Solution**: Ensure `clear_auto_discovered = True` in config
+
+**Issue**: Route parameters show wrong format
+**Solution**: Set `preserve_flask_routes` in config
+
+**Issue**: Security schemes not working
+**Solution**: Verify security scheme names match those in config
+
+**Issue**: Missing response schemas
+**Solution**: Check `add_default_responses` setting and `@spec.validate` decorators
+
+## 📄 License
+
+MIT License - feel free to use in your projects!
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality  
+4. Submit a pull request
+
+---
+
+**Created by Emmanuel Olowu** | [GitHub](https://github.com/zeddyemy) | [Website](https://eshomonu.com/)

quas_docs-0.0.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+quas_docs/__init__.py,sha256=x_JjDsweqFwPVfOfcB5RC4TUl_hChJi9Q4UK03EbUwo,804
+quas_docs/config.py,sha256=Kba_V7ClD0eT8qaCuG6RYJRpde_AMK-gPjEWmO8Y6zI,9198
+quas_docs/core.py,sha256=zOSGhhZ9b1REiTLHKCw_glBKNXPcgJbdzeUOAtrZvR8,20093
+quas_docs-0.0.3.dist-info/METADATA,sha256=f4Zs4tlqBKIk3WdQjDlhJ9UxeqQuS0c5d4DlkOFplAQ,14152
+quas_docs-0.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+quas_docs-0.0.3.dist-info/top_level.txt,sha256=Yr3-tV9MrBuJ2wZ-mKqpg_rHtUsFrXzKWhApgY8V_EE,10
+quas_docs-0.0.3.dist-info/RECORD,,

quas_docs-0.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quas_docs-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+quas_docs