vega-framework 0.2.1__tar.gz → 0.2.2__tar.gz

{vega_framework-0.2.1 → vega_framework-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vega-framework
-Version: 0.2.1
+Version: 0.2.2
 Summary: Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications.
 License: MIT
 License-File: LICENSE

{vega_framework-0.2.1 → vega_framework-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vega-framework"
-version = "0.2.1"
+version = "0.2.2"
 description = "Enterprise-ready Python framework that enforces Clean Architecture for building maintainable and scalable applications."
 authors = ["Roberto Ferro"]
 license = "MIT"

{vega_framework-0.2.1 → vega_framework-0.2.2}/vega/web/__init__.py

@@ -66,6 +66,10 @@ from .route_middleware import (
     middleware,
 )
 
+# OpenAPI / Documentation
+from .openapi import get_openapi_schema
+from .docs import get_swagger_ui_html, get_redoc_html
+
 __all__ = [
     # Version
     "__version__",
@@ -97,4 +101,8 @@ __all__ = [
     "RouteMiddleware",
     "MiddlewarePhase",
     "middleware",
+    # OpenAPI / Docs
+    "get_openapi_schema",
+    "get_swagger_ui_html",
+    "get_redoc_html",
 ]

{vega_framework-0.2.1 → vega_framework-0.2.2}/vega/web/application.py

@@ -7,10 +7,13 @@ from starlette.middleware import Middleware
 from starlette.middleware.cors import CORSMiddleware
 from starlette.routing import Mount, Route as StarletteRoute
 from starlette.types import ASGIApp
+from starlette.responses import JSONResponse as StarletteJSONResponse
 
 from .router import Router
 from .exceptions import HTTPException
 from .response import JSONResponse
+from .openapi import get_openapi_schema
+from .docs import get_swagger_ui_html, get_redoc_html
 
 
 class VegaApp:
@@ -59,12 +62,20 @@ class VegaApp:
         middleware: Optional[Sequence[Middleware]] = None,
         on_startup: Optional[Sequence[Callable]] = None,
         on_shutdown: Optional[Sequence[Callable]] = None,
+        docs_url: Optional[str] = "/docs",
+        redoc_url: Optional[str] = "/redoc",
+        openapi_url: Optional[str] = "/openapi.json",
     ):
         self.title = title
         self.description = description
         self.version = version
         self.debug = debug
 
+        # Documentation URLs (None to disable)
+        self.docs_url = docs_url
+        self.redoc_url = redoc_url
+        self.openapi_url = openapi_url
+
         # Internal router for top-level routes
         self._router = Router()
 
@@ -78,6 +89,9 @@ class VegaApp:
         # Starlette app (created lazily)
         self._starlette_app: Optional[Starlette] = None
 
+        # OpenAPI schema (cached)
+        self._openapi_schema: Optional[Dict[str, Any]] = None
+
     def add_middleware(
         self,
         middleware_class: type,
@@ -197,6 +211,22 @@ class VegaApp:
         """
         return self._router.route(path, methods, **kwargs)
 
+    def openapi(self) -> Dict[str, Any]:
+        """
+        Generate and return the OpenAPI schema.
+
+        Returns:
+            OpenAPI schema dictionary
+        """
+        if self._openapi_schema is None:
+            self._openapi_schema = get_openapi_schema(
+                title=self.title,
+                version=self.version,
+                description=self.description,
+                routes=self._router.get_routes(),
+            )
+        return self._openapi_schema
+
     def _build_starlette_app(self) -> Starlette:
         """Build the Starlette application from routes and middleware."""
         # Convert Vega routes to Starlette routes
@@ -204,6 +234,39 @@ class VegaApp:
             route.to_starlette_route() for route in self._router.get_routes()
         ]
 
+        # Add OpenAPI endpoint
+        if self.openapi_url:
+            async def openapi_endpoint(request):
+                return StarletteJSONResponse(self.openapi())
+
+            starlette_routes.append(
+                StarletteRoute(self.openapi_url, endpoint=openapi_endpoint, methods=["GET"])
+            )
+
+        # Add Swagger UI endpoint
+        if self.docs_url:
+            async def swagger_ui_endpoint(request):
+                return get_swagger_ui_html(
+                    openapi_url=self.openapi_url or "/openapi.json",
+                    title=f"{self.title} - Swagger UI"
+                )
+
+            starlette_routes.append(
+                StarletteRoute(self.docs_url, endpoint=swagger_ui_endpoint, methods=["GET"])
+            )
+
+        # Add ReDoc endpoint
+        if self.redoc_url:
+            async def redoc_endpoint(request):
+                return get_redoc_html(
+                    openapi_url=self.openapi_url or "/openapi.json",
+                    title=f"{self.title} - ReDoc"
+                )
+
+            starlette_routes.append(
+                StarletteRoute(self.redoc_url, endpoint=redoc_endpoint, methods=["GET"])
+            )
+
         # Create Starlette app
         app = Starlette(
             debug=self.debug,

vega_framework-0.2.2/vega/web/docs.py

@@ -0,0 +1,104 @@
+"""Documentation endpoints for Vega Web Framework"""
+
+from typing import Callable
+from starlette.responses import HTMLResponse, JSONResponse
+
+
+def get_swagger_ui_html(
+    *,
+    openapi_url: str,
+    title: str,
+    swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+    swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+) -> HTMLResponse:
+    """
+    Generate Swagger UI HTML page.
+
+    Args:
+        openapi_url: URL to OpenAPI schema JSON
+        title: Page title
+        swagger_js_url: URL to Swagger UI JavaScript
+        swagger_css_url: URL to Swagger UI CSS
+        swagger_favicon_url: URL to favicon
+
+    Returns:
+        HTML response with Swagger UI
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>{title}</title>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="shortcut icon" href="{swagger_favicon_url}">
+        <link rel="stylesheet" type="text/css" href="{swagger_css_url}" />
+    </head>
+    <body>
+        <div id="swagger-ui"></div>
+        <script src="{swagger_js_url}"></script>
+        <script>
+            const ui = SwaggerUIBundle({{
+                url: '{openapi_url}',
+                dom_id: '#swagger-ui',
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIBundle.SwaggerUIStandalonePreset
+                ],
+                layout: "BaseLayout",
+                deepLinking: true,
+                showExtensions: true,
+                showCommonExtensions: true
+            }})
+        </script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(content=html)
+
+
+def get_redoc_html(
+    *,
+    openapi_url: str,
+    title: str,
+    redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+    redoc_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+) -> HTMLResponse:
+    """
+    Generate ReDoc HTML page.
+
+    Args:
+        openapi_url: URL to OpenAPI schema JSON
+        title: Page title
+        redoc_js_url: URL to ReDoc JavaScript
+        redoc_favicon_url: URL to favicon
+
+    Returns:
+        HTML response with ReDoc
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>{title}</title>
+        <meta charset="utf-8"/>
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="shortcut icon" href="{redoc_favicon_url}">
+        <style>
+            body {{
+                margin: 0;
+                padding: 0;
+            }}
+        </style>
+    </head>
+    <body>
+        <redoc spec-url="{openapi_url}"></redoc>
+        <script src="{redoc_js_url}"></script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(content=html)
+
+
+__all__ = ["get_swagger_ui_html", "get_redoc_html"]

vega_framework-0.2.2/vega/web/openapi.py

@@ -0,0 +1,292 @@
+"""OpenAPI schema generation for Vega Web Framework"""
+
+from typing import Any, Dict, List, Optional, Type, get_type_hints
+from inspect import signature, Parameter
+import json
+
+try:
+    from pydantic import BaseModel
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+    BaseModel = None  # type: ignore
+
+
+def get_openapi_schema(
+    *,
+    title: str,
+    version: str,
+    description: str = "",
+    routes: List[Any],
+    openapi_version: str = "3.0.2",
+) -> Dict[str, Any]:
+    """
+    Generate OpenAPI 3.0 schema from routes.
+
+    Args:
+        title: API title
+        version: API version
+        description: API description
+        routes: List of Route objects
+        openapi_version: OpenAPI specification version
+
+    Returns:
+        OpenAPI schema dictionary
+    """
+    schema: Dict[str, Any] = {
+        "openapi": openapi_version,
+        "info": {
+            "title": title,
+            "version": version,
+        },
+        "paths": {},
+    }
+
+    if description:
+        schema["info"]["description"] = description
+
+    # Components for reusable schemas
+    components: Dict[str, Any] = {
+        "schemas": {}
+    }
+
+    # Process each route
+    for route in routes:
+        path = route.path
+
+        # Convert path parameters from {param} to OpenAPI format
+        openapi_path = path
+
+        if openapi_path not in schema["paths"]:
+            schema["paths"][openapi_path] = {}
+
+        for method in route.methods:
+            method_lower = method.lower()
+
+            operation: Dict[str, Any] = {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response"
+                    }
+                }
+            }
+
+            # Add summary and description
+            if route.summary:
+                operation["summary"] = route.summary
+
+            if route.description:
+                operation["description"] = route.description
+            elif route.endpoint.__doc__:
+                operation["description"] = route.endpoint.__doc__.strip()
+
+            # Add tags
+            if route.tags:
+                operation["tags"] = route.tags
+
+            # Add operation ID
+            operation["operationId"] = f"{method_lower}_{route.name or route.endpoint.__name__}"
+
+            # Analyze endpoint parameters
+            params = _get_parameters(route)
+            if params:
+                operation["parameters"] = params
+
+            # Analyze request body
+            request_body = _get_request_body(route)
+            if request_body:
+                operation["requestBody"] = request_body
+                # Add request body schemas to components
+                if PYDANTIC_AVAILABLE and "content" in request_body:
+                    for content_type, content_schema in request_body["content"].items():
+                        if "schema" in content_schema and "$ref" in content_schema["schema"]:
+                            model_name = content_schema["schema"]["$ref"].split("/")[-1]
+                            # Model will be added when processing response_model
+
+            # Analyze response model
+            if route.response_model:
+                response_schema = _get_response_schema(route.response_model, components)
+                if response_schema:
+                    operation["responses"]["200"] = {
+                        "description": "Successful Response",
+                        "content": {
+                            "application/json": {
+                                "schema": response_schema
+                            }
+                        }
+                    }
+
+            # Add status code if specified
+            if route.status_code and route.status_code != 200:
+                operation["responses"][str(route.status_code)] = operation["responses"].pop("200")
+
+            # Add error responses
+            operation["responses"]["422"] = {
+                "description": "Validation Error"
+            }
+
+            schema["paths"][openapi_path][method_lower] = operation
+
+    # Add components if we have any schemas
+    if components["schemas"]:
+        schema["components"] = components
+
+    return schema
+
+
+def _get_parameters(route: Any) -> List[Dict[str, Any]]:
+    """Extract path and query parameters from route."""
+    parameters = []
+
+    # Get function signature
+    sig = signature(route.endpoint)
+    type_hints = get_type_hints(route.endpoint)
+
+    # Find which parameters are Pydantic models (request body)
+    request_body_params = set()
+    if PYDANTIC_AVAILABLE:
+        for param_name, param in sig.parameters.items():
+            param_type = type_hints.get(param_name)
+            if param_type and isinstance(param_type, type) and issubclass(param_type, BaseModel):
+                request_body_params.add(param_name)
+
+    for param_name, param in sig.parameters.items():
+        # Skip special parameters
+        if param_name in ("request", "self", "cls"):
+            continue
+
+        # Skip parameters that are Pydantic models (they're in request body)
+        if param_name in request_body_params:
+            continue
+
+        # Check if it's a path parameter
+        if f"{{{param_name}}}" in route.path:
+            param_schema = {
+                "name": param_name,
+                "in": "path",
+                "required": True,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            parameters.append(param_schema)
+        elif param.default == Parameter.empty:
+            # Required query parameter
+            param_schema = {
+                "name": param_name,
+                "in": "query",
+                "required": True,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            parameters.append(param_schema)
+        else:
+            # Optional query parameter
+            param_schema = {
+                "name": param_name,
+                "in": "query",
+                "required": False,
+                "schema": _get_type_schema(type_hints.get(param_name, str))
+            }
+            if param.default is not None and param.default != Parameter.empty:
+                param_schema["schema"]["default"] = param.default
+            parameters.append(param_schema)
+
+    return parameters
+
+
+def _get_request_body(route: Any) -> Optional[Dict[str, Any]]:
+    """Extract request body schema from route."""
+    if not PYDANTIC_AVAILABLE:
+        return None
+
+    # Get function signature
+    sig = signature(route.endpoint)
+    type_hints = get_type_hints(route.endpoint)
+
+    for param_name, param in sig.parameters.items():
+        # Skip special parameters and path parameters
+        if param_name in ("request", "self", "cls"):
+            continue
+        if f"{{{param_name}}}" in route.path:
+            continue
+
+        param_type = type_hints.get(param_name)
+
+        # Check if it's a Pydantic model
+        if param_type and isinstance(param_type, type) and issubclass(param_type, BaseModel):
+            model_schema = param_type.model_json_schema()
+            model_name = param_type.__name__
+
+            return {
+                "required": True,
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "$ref": f"#/components/schemas/{model_name}"
+                        }
+                    }
+                }
+            }
+
+    return None
+
+
+def _get_response_schema(response_model: Type, components: Dict[str, Any]) -> Dict[str, Any]:
+    """Get response schema from response model."""
+    if not PYDANTIC_AVAILABLE:
+        return {}
+
+    # Handle Pydantic models
+    if isinstance(response_model, type) and issubclass(response_model, BaseModel):
+        model_name = response_model.__name__
+
+        # Add model schema to components
+        if model_name not in components["schemas"]:
+            components["schemas"][model_name] = response_model.model_json_schema()
+
+        return {
+            "$ref": f"#/components/schemas/{model_name}"
+        }
+
+    # Handle List types
+    if hasattr(response_model, "__origin__"):
+        if response_model.__origin__ is list:
+            item_type = response_model.__args__[0]
+            if isinstance(item_type, type) and issubclass(item_type, BaseModel):
+                model_name = item_type.__name__
+
+                # Add model schema to components
+                if model_name not in components["schemas"]:
+                    components["schemas"][model_name] = item_type.model_json_schema()
+
+                return {
+                    "type": "array",
+                    "items": {
+                        "$ref": f"#/components/schemas/{model_name}"
+                    }
+                }
+
+    # Handle dict
+    if response_model is dict:
+        return {"type": "object"}
+
+    return {}
+
+
+def _get_type_schema(param_type: Any) -> Dict[str, Any]:
+    """Convert Python type to OpenAPI schema."""
+    if param_type is str or param_type == "str":
+        return {"type": "string"}
+    elif param_type is int or param_type == "int":
+        return {"type": "integer"}
+    elif param_type is float or param_type == "float":
+        return {"type": "number"}
+    elif param_type is bool or param_type == "bool":
+        return {"type": "boolean"}
+    elif param_type is list or (hasattr(param_type, "__origin__") and param_type.__origin__ is list):
+        return {"type": "array", "items": {}}
+    elif param_type is dict:
+        return {"type": "object"}
+    else:
+        return {"type": "string"}
+
+
+__all__ = ["get_openapi_schema"]