Automatically docs are available when jsweb run

Author: kasimlyee

jsweb/cli.py

@@ -345,6 +345,31 @@ def cli():
             from jsweb.database import init_db
             init_db(config.DATABASE_URL)
 
+            # Automatically setup OpenAPI documentation (unless disabled in config)
+            if getattr(config, 'ENABLE_OPENAPI_DOCS', True):
+                try:
+                    from jsweb.docs import setup_openapi_docs
+                    from jsweb.docs.introspection import introspect_app_routes
+
+                    # Introspect routes first
+                    introspect_app_routes(app_instance)
+
+                    # Setup docs with config values or defaults
+                    setup_openapi_docs(
+                        app_instance,
+                        title=getattr(config, 'API_TITLE', 'jsweb API'),
+                        version=getattr(config, 'API_VERSION', '1.0.0'),
+                        description=getattr(config, 'API_DESCRIPTION', ''),
+                        docs_url=getattr(config, 'OPENAPI_DOCS_URL', '/docs'),
+                        redoc_url=getattr(config, 'OPENAPI_REDOC_URL', '/redoc'),
+                        openapi_url=getattr(config, 'OPENAPI_JSON_URL', '/openapi.json'),
+                    )
+                except ImportError:
+                    # Pydantic not installed, skip OpenAPI setup
+                    pass
+                except Exception as e:
+                    logger.warning(f"⚠️  Could not setup OpenAPI docs: {e}")
+
             host = args.host or config.HOST
             port = args.port or config.PORT
 

jsweb/docs/__init__.py

@@ -22,6 +22,7 @@
 )
 from .setup import setup_openapi_docs, configure_openapi, add_security_scheme
 from .registry import openapi_registry
+from .auto_validation import disable_auto_validation
 
 __all__ = [
     # Decorators
@@ -38,6 +39,9 @@
     'configure_openapi',
     'add_security_scheme',
 
+    # Utilities
+    'disable_auto_validation',
+
     # Registry (for advanced usage)
     'openapi_registry',
 ]

jsweb/docs/auto_validation.py

@@ -0,0 +1,133 @@
+"""
+Automatic request/response validation - FastAPI-style
+
+This module provides automatic validation when DTOs are used,
+with option to disable if needed.
+"""
+
+from functools import wraps
+from typing import Type, get_type_hints
+import inspect
+from pydantic import ValidationError as PydanticValidationError
+
+
+def validate_request_body(dto_class: Type):
+    """
+    Decorator that automatically validates request body against a DTO.
+
+    This is automatically applied when @api_body is used.
+
+    Args:
+        dto_class: The DTO class to validate against
+
+    Example:
+        @api_body(CreateUserDto)  # Automatically adds validation
+        async def create_user(req):
+            # req.validated_body is the validated DTO instance
+            return json(req.validated_body.to_dict())
+    """
+    def decorator(handler):
+        @wraps(handler)
+        async def wrapper(req, *args, **kwargs):
+            # Parse request body
+            try:
+                if hasattr(req, 'json'):
+                    data = await req.json()
+                else:
+                    # Fallback for testing
+                    data = {}
+
+                # Validate with DTO
+                validated = dto_class(**data)
+
+                # Attach validated DTO to request
+                req.validated_body = validated
+                req.validated_data = validated.to_dict()
+
+            except PydanticValidationError as e:
+                # Return validation error response
+                from jsweb.response import JSONResponse
+                errors = []
+                for error in e.errors():
+                    errors.append({
+                        "field": ".".join(str(x) for x in error["loc"]),
+                        "message": error["msg"],
+                        "type": error["type"]
+                    })
+
+                return JSONResponse({
+                    "error": "Validation failed",
+                    "details": errors
+                }, status=400)
+
+            except Exception as e:
+                # Return generic error
+                from jsweb.response import JSONResponse
+                return JSONResponse({
+                    "error": "Invalid request body",
+                    "details": str(e)
+                }, status=400)
+
+            # Call original handler
+            return await handler(req, *args, **kwargs)
+
+        # Mark as validated
+        wrapper._jsweb_validated = True
+        wrapper._jsweb_dto_class = dto_class
+
+        return wrapper
+    return decorator
+
+
+def auto_serialize_response(dto_class: Type, status_code: int = 200):
+    """
+    Decorator that automatically serializes DTO responses to JSON.
+
+    Example:
+        @api_response(200, UserDto)  # Can optionally add auto-serialization
+        async def get_user(req, user_id):
+            user = UserDto(id=user_id, name="John", ...)
+            return user  # Automatically converts to JSONResponse
+    """
+    def decorator(handler):
+        @wraps(handler)
+        async def wrapper(req, *args, **kwargs):
+            result = await handler(req, *args, **kwargs)
+
+            # If result is already a Response, return as-is
+            if hasattr(result, 'status_code') or isinstance(result, dict):
+                return result
+
+            # If result is a DTO instance, serialize it
+            if hasattr(result, 'to_dict'):
+                from jsweb.response import JSONResponse
+                return JSONResponse(result.to_dict(), status=status_code)
+
+            # If result is a list of DTOs
+            if isinstance(result, list) and result and hasattr(result[0], 'to_dict'):
+                from jsweb.response import JSONResponse
+                return JSONResponse([item.to_dict() for item in result], status=status_code)
+
+            # Return as-is
+            return result
+
+        return wrapper
+    return decorator
+
+
+def disable_auto_validation(handler):
+    """
+    Decorator to disable automatic validation for a specific route.
+
+    Use this when you want the documentation but not the validation.
+
+    Example:
+        @api_body(CreateUserDto)
+        @disable_auto_validation
+        async def create_user(req):
+            # Validation is skipped, but docs still generated
+            data = await req.json()  # Manual handling
+            return json(data)
+    """
+    handler._jsweb_disable_validation = True
+    return handler

jsweb/docs/decorators.py

@@ -1,14 +1,12 @@
 """
-NestJS-style decorators for API documentation
+Decorators for API documentation
 
 These decorators allow developers to add rich OpenAPI documentation to their routes.
 """
 
-from functools import wraps
-from typing import Type, Dict, Any, List, Optional, Union
+from typing import Type, Dict, Any, List
 from .registry import (
     openapi_registry,
-    RouteMetadata,
     ResponseMetadata,
     RequestBodyMetadata,
     ParameterMetadata
@@ -22,7 +20,7 @@ def api_operation(
     deprecated: bool = False,
 ):
     """
-    Document an API operation (NestJS-style).
+    Document an API operation 
 
     This decorator should be placed closest to the route decorator.
 
@@ -122,32 +120,44 @@ def api_body(
     description: str = "",
     content_type: str = "application/json",
     required: bool = True,
-    examples: Dict[str, Any] = None
+    examples: Dict[str, Any] = None,
+    auto_validate: bool = True  # NEW: Enable/disable automatic validation
 ):
     """
-    Document request body (NestJS-style).
+    Document request body with AUTOMATIC VALIDATION (FastAPI-style).
 
-    The DTO class will be used for:
-    1. OpenAPI schema generation
-    2. Automatic request validation (via middleware)
+    By default, this decorator:
+    1. Generates OpenAPI schema documentation
+    2. Automatically validates incoming requests against the DTO
+    3. Provides validated data via req.validated_body
 
     Args:
         dto: Request body DTO class (JswebBaseModel subclass)
         description: Body description
         content_type: MIME type
         required: Whether body is required
         examples: Example request bodies
+        auto_validate: Enable automatic validation (default: True)
 
     Example:
         @api_bp.route("/users", methods=["POST"])
         @api_body(CreateUserDto, description="User data to create")
         @api_response(201, UserDto, description="User created")
         async def create_user(req):
-            # req.validated_body will contain the validated DTO instance
-            data = await req.json()
-            return json({"user": {...}}, status=201)
+            # req.validated_body contains the validated DTO instance
+            # req.validated_data contains the dict representation
+            user_data = req.validated_data
+            return json({"user": user_data}, status=201)
+
+        # Disable auto-validation if needed:
+        @api_body(CreateUserDto, auto_validate=False)
+        async def create_user_manual(req):
+            data = await req.json()  # Manual handling
+            return json(data)
     """
     def decorator(handler):
+        from .auto_validation import validate_request_body
+
         metadata = openapi_registry.get_or_create_route(handler)
 
         # Get schema from DTO
@@ -168,10 +178,15 @@ def decorator(handler):
             dto_class=dto  # Store for automatic validation
         )
 
-        # Mark handler with validation info (for middleware)
+        # Apply automatic validation unless disabled
+        if auto_validate and not getattr(handler, '_jsweb_disable_validation', False):
+            handler = validate_request_body(dto)(handler)
+
+        # Mark handler with validation info
         if not hasattr(handler, '_jsweb_validation'):
             handler._jsweb_validation = {}
         handler._jsweb_validation['body_dto'] = dto
+        handler._jsweb_validation['auto_validate'] = auto_validate
 
         return handler
     return decorator
@@ -241,7 +256,7 @@ def api_header(
     **schema_kwargs
 ):
     """
-    Document a header parameter (NestJS-style).
+    Document a header parameter 
 
     Args:
         name: Header name (e.g., 'Authorization', 'X-API-Key')
@@ -283,7 +298,7 @@ def decorator(handler):
 
 def api_security(*schemes: str, scopes: List[str] = None):
     """
-    Apply security requirements to an operation (NestJS-style).
+    Apply security requirements to an operation 
 
     Args:
         *schemes: Security scheme names (must be registered)
@@ -320,7 +335,7 @@ def decorator(handler):
 
 def api_tags(*tags: str):
     """
-    Add tags to an operation for grouping in documentation (NestJS-style).
+    Add tags to an operation for grouping in documentation 
 
     Args:
         *tags: Tag names

jsweb/docs/validation_middleware.py

@@ -0,0 +1,42 @@
+"""
+Optional automatic request validation middleware
+
+This middleware automatically validates request bodies against DTOs
+when @api_body decorator is used.
+"""
+
+from jsweb.request import Request
+from jsweb.response import JSONResponse
+from .registry import openapi_registry
+
+
+class ValidationMiddleware:
+    """
+    ASGI middleware that validates requests against DTOs.
+
+    Usage:
+        from jsweb import JsWebApp
+        from jsweb.docs.validation_middleware import ValidationMiddleware
+
+        app = JsWebApp(__name__)
+        app.add_middleware(ValidationMiddleware)
+    """
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Create request object to inspect
+        request = Request(scope, receive, send)
+
+        # Find route metadata
+        # Note: This requires access to the handler which we don't have here
+        # This is a simplified example - full implementation would need
+        # integration with the routing system
+
+        # For now, just pass through
+        await self.app(scope, receive, send)

jsweb/project_templates/config.py.jinja

@@ -12,3 +12,14 @@ BASE_DIR = os.path.abspath(os.path.dirname(__file__))
 DATABASE_URL = f"sqlite:///{os.path.join(BASE_DIR, 'jsweb.db')}"
 HOST = "127.0.0.1"
 PORT = 8000
+
+# OpenAPI / Swagger Documentation (Automatic!)
+# Docs are automatically available at /docs, /redoc, and /openapi.json
+# Set ENABLE_OPENAPI_DOCS = False to disable
+ENABLE_OPENAPI_DOCS = True           # Enable automatic API documentation
+API_TITLE = "{{ project_name | capitalize }} API"
+API_VERSION = "1.0.0"
+API_DESCRIPTION = "API documentation for {{ project_name | capitalize }}"
+OPENAPI_DOCS_URL = "/docs"           # Swagger UI
+OPENAPI_REDOC_URL = "/redoc"         # ReDoc UI
+OPENAPI_JSON_URL = "/openapi.json"   # OpenAPI spec JSON

pyproject.toml

@@ -40,7 +40,8 @@ dependencies = [
     "itsdangerous",
     "alembic",
     "markupsafe",
-    "uvicorn"
+    "uvicorn",
+    "pydantic>=2.0,<3.0"  # Required for DTO system and OpenAPI docs
 ]
 
 [project.optional-dependencies]