Merge pull request #13 from kasimlyee/lyee/docs

Added OpenAPI Documentation System

Author: Jones-peter

JSWEB_OPENAPI_GUIDE.md

@@ -0,0 +1,369 @@
+"""
+Example jsweb API with OpenAPI Documentation
+
+This example demonstrates:
+- DTO definitions with validation
+- NestJS-style route documentation
+- Automatic OpenAPI generation
+- Swagger UI and ReDoc interfaces
+"""
+
+from jsweb import JsWebApp, Blueprint
+try:
+    from jsweb.response import JSONResponse as json
+except ImportError:
+    # Fallback for this example
+    def json(data, status=200):
+        import json as json_module
+        return {
+            'status': status,
+            'headers': {'Content-Type': 'application/json'},
+            'body': json_module.dumps(data)
+        }
+
+# Import DTO system
+from jsweb.dto import JswebBaseModel, Field, validator
+
+# Import documentation decorators
+from jsweb.docs import (
+    setup_openapi_docs,
+    api_operation,
+    api_response,
+    api_body,
+    api_query,
+    api_tags,
+    api_security,
+    add_security_scheme
+)
+
+# ============================================================================
+# DTOs (Data Transfer Objects)
+# ============================================================================
+
+class UserDto(JswebBaseModel):
+    """User data model."""
+    id: int = Field(description="User ID", example=1)
+    name: str = Field(
+        description="User's full name",
+        min_length=1,
+        max_length=100,
+        example="John Doe"
+    )
+    email: str = Field(
+        description="Email address",
+        pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$',
+        example="[email protected]"
+    )
+    age: int = Field(
+        ge=0,
+        le=150,
+        description="User's age in years",
+        example=30
+    )
+    role: str = Field(
+        description="User role",
+        example="user"
+    )
+
+
+class CreateUserDto(JswebBaseModel):
+    """DTO for creating a new user."""
+    name: str = Field(
+        min_length=1,
+        max_length=100,
+        description="User name"
+    )
+    email: str = Field(
+        pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$',
+        description="Valid email address"
+    )
+    age: int = Field(ge=0, le=150, description="User age")
+
+    @validator('name')
+    @classmethod
+    def validate_name(cls, value):
+        """Validate and normalize name."""
+        if value.strip() == '':
+            raise ValueError('Name cannot be empty')
+        return value.strip()
+
+    @validator('email')
+    @classmethod
+    def validate_email(cls, value):
+        """Normalize email to lowercase."""
+        return value.lower()
+
+
+class UpdateUserDto(JswebBaseModel):
+    """DTO for updating a user (all fields optional)."""
+    name: str = Field(None, min_length=1, max_length=100)
+    email: str = Field(None, pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
+    age: int = Field(None, ge=0, le=150)
+
+
+class ErrorDto(JswebBaseModel):
+    """Error response model."""
+    error: str = Field(description="Error message")
+    code: int = Field(description="Error code", example=400)
+    details: dict = Field(default_factory=dict, description="Additional error details")
+
+
+# ============================================================================
+# API Blueprint
+# ============================================================================
+
+api = Blueprint('api', url_prefix='/api')
+
+# Mock database
+USERS_DB = [
+    {"id": 1, "name": "John Doe", "email": "[email protected]", "age": 30, "role": "admin"},
+    {"id": 2, "name": "Jane Smith", "email": "[email protected]", "age": 25, "role": "user"},
+    {"id": 3, "name": "Bob Johnson", "email": "[email protected]", "age": 35, "role": "user"},
+]
+
+
+@api.route("/users", methods=["GET"])
+@api_tags("Users")
+@api_operation(
+    summary="List all users",
+    description="Returns a paginated list of all users in the system. "
+                "You can filter by role and search by name."
+)
+@api_query('page', type=int, required=False, description="Page number (starts at 1)", example=1)
+@api_query('limit', type=int, required=False, description="Items per page (max 100)", example=10)
+@api_query('role', type=str, required=False, description="Filter by role (admin, user)")
+@api_query('search', type=str, required=False, description="Search in user names")
+@api_response(200, UserDto, description="List of users")
+async def list_users(req):
+    """Get all users with optional filtering."""
+    page = int(req.query_params.get('page', 1)) if hasattr(req, 'query_params') else 1
+    limit = int(req.query_params.get('limit', 10)) if hasattr(req, 'query_params') else 10
+
+    users = USERS_DB.copy()
+    return json({
+        "users": users,
+        "page": page,
+        "limit": limit,
+        "total": len(users)
+    })
+
+
+@api.route("/users/<int:user_id>", methods=["GET"])
+@api_tags("Users")
+@api_operation(
+    summary="Get user by ID",
+    description="Retrieves a single user by their unique ID"
+)
+@api_response(200, UserDto, description="User found")
+@api_response(404, ErrorDto, description="User not found")
+async def get_user(req, user_id):
+    """Get a specific user by ID."""
+    user = next((u for u in USERS_DB if u["id"] == user_id), None)
+
+    if not user:
+        return json({
+            "error": "User not found",
+            "code": 404
+        }, status=404)
+
+    return json(user)
+
+
+@api.route("/users", methods=["POST"])
+@api_tags("Users")
+@api_operation(
+    summary="Create new user",
+    description="Creates a new user in the system. "
+                "Email must be unique."
+)
+@api_body(CreateUserDto, description="User data")
+@api_response(201, UserDto, description="User created successfully")
+@api_response(400, ErrorDto, description="Validation error")
+@api_response(409, ErrorDto, description="Email already exists")
+async def create_user(req):
+    """Create a new user."""
+    try:
+        data = await req.json() if hasattr(req, 'json') else {}
+
+        # Validate with DTO (in production)
+        # user_dto = CreateUserDto(**data)
+
+        # Check email uniqueness
+        if any(u["email"] == data.get("email") for u in USERS_DB):
+            return json({
+                "error": "Email already exists",
+                "code": 409
+            }, status=409)
+
+        # Create user
+        new_user = {
+            "id": len(USERS_DB) + 1,
+            "role": "user",
+            **data
+        }
+        USERS_DB.append(new_user)
+
+        return json(new_user, status=201)
+
+    except Exception as e:
+        return json({
+            "error": str(e),
+            "code": 400
+        }, status=400)
+
+
+@api.route("/users/<int:user_id>", methods=["PATCH"])
+@api_tags("Users")
+@api_operation(
+    summary="Update user",
+    description="Updates an existing user. All fields are optional."
+)
+@api_body(UpdateUserDto, description="Fields to update")
+@api_response(200, UserDto, description="User updated successfully")
+@api_response(404, ErrorDto, description="User not found")
+@api_response(400, ErrorDto, description="Validation error")
+async def update_user(req, user_id):
+    """Update an existing user."""
+    user = next((u for u in USERS_DB if u["id"] == user_id), None)
+
+    if not user:
+        return json({
+            "error": "User not found",
+            "code": 404
+        }, status=404)
+
+    try:
+        data = await req.json() if hasattr(req, 'json') else {}
+        user.update(data)
+        return json(user)
+    except Exception as e:
+        return json({
+            "error": str(e),
+            "code": 400
+        }, status=400)
+
+
+@api.route("/users/<int:user_id>", methods=["DELETE"])
+@api_tags("Users")
+@api_operation(
+    summary="Delete user",
+    description="Permanently deletes a user from the system"
+)
+@api_response(204, description="User deleted successfully")
+@api_response(404, ErrorDto, description="User not found")
+@api_security("bearer_auth")
+async def delete_user(req, user_id):
+    """Delete a user (requires authentication)."""
+    global USERS_DB
+    user = next((u for u in USERS_DB if u["id"] == user_id), None)
+
+    if not user:
+        return json({
+            "error": "User not found",
+            "code": 404
+        }, status=404)
+
+    USERS_DB = [u for u in USERS_DB if u["id"] != user_id]
+    return json(None, status=204)
+
+
+@api.route("/health", methods=["GET"])
+@api_tags("System")
+@api_operation(
+    summary="Health check",
+    description="Check if the API is running"
+)
+@api_response(200, description="API is healthy")
+async def health_check(req):
+    """Check API health."""
+    return json({"status": "ok", "version": "1.0.0"})
+
+
+# ============================================================================
+# App Setup
+# ============================================================================
+
+def create_app():
+    """Create and configure the jsweb application."""
+    app = JsWebApp(__name__)
+
+    # Register blueprints FIRST
+    app.register_blueprint(api)
+
+    # Setup OpenAPI documentation (MUST be after blueprint registration!)
+    setup_openapi_docs(
+        app,
+        title="User Management API",
+        version="1.0.0",
+        description="""
+# User Management API
+
+A simple RESTful API for managing users, built with jsweb framework.
+
+## Features
+
+- ✅ CRUD operations for users
+- ✅ Input validation with Pydantic
+- ✅ Automatic OpenAPI documentation
+- ✅ JWT authentication support
+- ✅ Search and filtering
+
+## Authentication
+
+Some endpoints require a Bearer token. Use the **Authorize** button above to add your token.
+        """,
+        contact={
+            "name": "API Support",
+            "email": "[email protected]",
+            "url": "https://example.com/support"
+        },
+        license_info={
+            "name": "MIT",
+            "url": "https://opensource.org/licenses/MIT"
+        },
+        tags=[
+            {
+                "name": "Users",
+                "description": "User management operations"
+            },
+            {
+                "name": "System",
+                "description": "System health and status"
+            }
+        ],
+        security_schemes={
+            "bearer_auth": {
+                "type": "http",
+                "scheme": "bearer",
+                "bearerFormat": "JWT",
+                "description": "Enter your JWT token"
+            }
+        }
+    )
+
+    return app
+
+
+# ============================================================================
+# Run
+# ============================================================================
+
+if __name__ == "__main__":
+    from jsweb.server import run
+
+    app = create_app()
+
+    print("\n" + "="*60)
+    print("[*] Example API with OpenAPI Documentation")
+    print("="*60)
+    PORT = 8001
+    print(f"\nStarting server on http://localhost:{PORT}")
+    print("\nAvailable endpoints:")
+    print(f"  > Swagger UI:    http://localhost:{PORT}/docs")
+    print(f"  > ReDoc:         http://localhost:{PORT}/redoc")
+    print(f"  > OpenAPI JSON:  http://localhost:{PORT}/openapi.json")
+    print("\nPress Ctrl+C to stop")
+    print("="*60 + "\n")
+
+    # Note: reload doesn't work when passing app directly
+    run(app, host="127.0.0.1", port=PORT, reload=False)