feat(docs): Introduce decorator-based route mapping for REST controllers

- Added support for a declarative approach to route definition using decorators like `@GetMapping` and `@PostMapping`, enhancing code organization and type safety.
- Updated documentation to reflect changes in the `RestController` class, including examples and key benefits of the new routing method.

Author: William-W-Chen

docs/guide/entities-in-framework/rest-controller.md

@@ -19,12 +19,13 @@ The `RestController` class in PySpring serves as a base class for building RESTf
 
 ### Create a Controller Class
 
-Extend the `RestController` class and override the `register_routes()` method to define routes. Optionally, override `register_middlewares()` to add middleware.
+Extend the `RestController` class and use the route mapping decorators to define your API endpoints. Optionally, override `register_middlewares()` to add middleware.
 
 ### Example:
 
 ```py
 from py_spring_core import RestController
+from py_spring_core import GetMapping, PostMapping
 from fastapi import HTTPException
 from pydantic import BaseModel
 
@@ -36,24 +37,23 @@ class MyController(RestController):
     class Config:
         prefix = "/api/items"  # Base URL prefix for this controller
 
-    def register_routes(self):
-        @self.router.get("/")
-        def read_items():
-            return {"message": "List of items"}
+    @GetMapping("/")
+    def read_items(self):
+        return {"message": "List of items"}
 
-        @self.router.get("/{item_id}")
-        def read_item(item_id: int):
-            return {"message": f"Details for item {item_id}"}
+    @GetMapping("/{item_id}")
+    def read_item(self, item_id: int):
+        return {"message": f"Details for item {item_id}"}
 
-        @self.router.post("/", status_code=201)
-        def create_item(item: Item):
-            return item
+    @PostMapping("/", status_code=201)
+    def create_item(self, item: Item):
+        return item
 ```
 
 ### Key Points:
 
 -   Use the `Config` inner class to set the route prefix.
--   Define routes using the `@self.router` decorator.
+-   Define routes using the route mapping decorators (`@GetMapping`, `@PostMapping`, etc.).
 
 * * * * *
 
@@ -62,72 +62,69 @@ class MyController(RestController):
 2.  The `_handle_register_rest_controller()` method:
     -   Registers the controller with the application context.
     -   Initializes an `APIRouter` instance.
-    -   Calls `register_routes()` to add routes.
+    -   Automatically registers routes defined with decorators.
     -   Includes the controller's router in the main FastAPI application.
     -   Calls `register_middlewares()` for middleware registration.
 
 * * * * *
 
 ### Defining Routes
-Use `@self.router` decorators to define API endpoints inside `register_routes()`:
+PySpring provides a declarative approach to route definition using decorators, similar to Spring's annotation-based routing. This provides a cleaner and more type-safe way to define API endpoints.
 
-```py
-@self.router.get("/")
-def read_items():
-    return {"message": "List of items"}
-
-@self.router.post("/", status_code=201)
-def create_item(item: Item):
-    return item
-```
-### Example:
-
--   `GET /` maps to the `read_items` method.
--   `POST /` maps to the `create_item` method.
+#### Available Decorators:
+- `@GetMapping`: For HTTP GET requests
+- `@PostMapping`: For HTTP POST requests
+- `@PutMapping`: For HTTP PUT requests
+- `@DeleteMapping`: For HTTP DELETE requests
+- `@PatchMapping`: For HTTP PATCH requests
 
-### FastAPI Features:
-
--   Dependency Injection
--   Request body handling
--   Path parameter parsing
-
-* * * * *
-
-### Defining Middlewares
-Override `register_middlewares()` to add middleware. Use `app.middleware()` to define custom middleware functions.
+#### Example Usage:
+```python
+from py_spring_core import RestController
+from py_spring_core import GetMapping, PostMapping, PutMapping, DeleteMapping
+from pydantic import BaseModel
 
-### Example:
+class User(BaseModel):
+    name: str
+    email: str
 
-```py
-def register_middlewares(self):
-    @self.app.middleware("http")
-    async def add_process_time_header(request, call_next):
-        start_time = time.time()
-        response = await call_next(request)
-        process_time = time.time() - start_time
-        response.headers["X-Process-Time"] = str(process_time)
-        return response
+class UserController(RestController):
+    class Config:
+        prefix = "/api/users"
+
+    @GetMapping("/")
+    def get_users(self):
+        return {"users": []}
+        
+    @GetMapping("/{user_id}")
+    def get_user(self, user_id: int):
+        return {"user_id": user_id}
+        
+    @PostMapping("/")
+    def create_user(self, user: User):
+        return {"message": "User created", "user": user}
+        
+    @PutMapping("/{user_id}")
+    def update_user(self, user_id: int, user: User):
+        return {"message": f"User {user_id} updated", "user": user}
+        
+    @DeleteMapping("/{user_id}")
+    def delete_user(self, user_id: int):
+        return {"message": f"User {user_id} deleted"}
 ```
-### Common Middleware Use Cases:
--   Authentication
--   Authorization
--   Logging
--   Performance metrics
-
-### Accessing FastAPI Components
--   **`self.app`**: The main FastAPI application instance.
--   **`self.router`**: The APIRouter instance for the controller.
 
+#### Key Benefits:
+1. **Type Safety**: Decorators provide better type checking and IDE support
+2. **Cleaner Code**: Route definitions are more concise and readable
+3. **Automatic Registration**: Routes are automatically registered during application initialization
+4. **Class-Level Prefixing**: Still supports the `Config.prefix` for base URL prefixing
+5. **Preserved Metadata**: Function metadata is preserved using `functools.wraps`
 
-### Important Considerations
-1.  **Class Configuration**: Use the `Config` class to define the URL prefix.
-2.  **Route Registration**: Ensure all routes are defined in `register_routes()` using `@self.router`.
-3.  **Middleware Registration**: Add middleware in `register_middlewares()` using `app.middleware()`.
-4.  **Dependency Injection**: In this class, you can leverage both PySpring's and FastAPI's dependency injection systems to manage dependencies efficiently.
-5.  **Error Handling**: Use `HTTPException` for proper error responses and integrate with PySpring's error handling mechanisms.
-6.  **Code Organization**: Keep controllers focused on request handling and delegate business logic to services or components.
+#### Technical Details:
+- Routes are stored in a static `RouteMapping.routes` dictionary
+- Each route is registered with its HTTP method, path, and handler function
+- Route registration happens during application initialization
+- Decorators preserve function metadata for better introspection
 
-* * * * *
-
-### Summary
-The `RestController` class helps build well-structured, maintainable, and scalable RESTful APIs in PySpring. By utilizing its features like routing, middleware support, and integration with FastAPI, developers can focus on creating efficient APIs while maintaining code clarity and modularity.
+### Defining Middlewares
+Override `register_middlewares()`

docs/index.md

@@ -39,6 +39,8 @@
 
 - **Component Registration Validation**: The framework includes robust validation to prevent duplicate component registration and provides clear error messages for developers. This ensures that your application maintains a clean and consistent component structure.
 
+- **Decorator-Based Route Mapping**: PySpring now supports a more declarative approach to route definition using decorators, similar to Spring's annotation-based routing. This provides a cleaner and more type-safe way to define API endpoints with better IDE support and code organization.
+
 ### Getting Started
 To get started with **PySpring**, follow these steps: