Merge pull request #46 from eadwinCode/documentation_fix

Clear Written Documentation

Author: eadwinCode

README.md

@@ -8,8 +8,8 @@
 
 # Django Ninja Extra
 
-**Django Ninja Extra** is a complete class-based fashion of building and setting up APIs at incredible speed with incredible performance.
-It utilizes [**Django Ninja**](https://django-ninja.rest-framework.com) core features without compromising speed.
+The **Django Ninja Extra** package offers a convenient, **class-based** approach to quickly building and configuring high-performance APIs. 
+Utilizing the core features of [**Django Ninja**](https://django-ninja.rest-framework.com), it allows for speedy development without sacrificing performance."
 
 **Key features:**
 

docs/api_controller/index.md

@@ -1,35 +1,100 @@
 # **Controller**
+The term 'APIController' is borrowed from the C# ASP.NET environment, which uses the MVC framework. Although Django is not an MVC framework, it is still possible to mimic the concept by using similar patterns and principles.
+Django-Ninja-Extra's APIController is modeled after the C# ASP.NET ApiController, providing an object-oriented approach to creating controller models and implementing modern software design patterns in your Django project. This allows you to use similar concepts and design patterns as in C# ASP.NET environment in your Django project.
 
-APIController is a borrowed term from the C# ASP.NET environment which is an MVC framework. Although Django is not an MVC framework, we can still mimic the concept generally just like any other programming concept.
+### Why APIController in Django.
 
-Django-Ninja-Extra APIController is modelled after C# ASP.NET ApiController, giving all OOP sense in creating your controller models and adapting recent software design patterns in your Django project.
+Coming from a background of modeling objects using class-based approaches, and having experience working with various API tools such as DRF, FastAPI, and Flask-Restful, you have likely noticed that these libraries primarily use function-based or class-tailored function-based approaches in writing route functions. This approach may not fully utilize the concepts of object-oriented programming when designing RESTful APIs. But despite this, these libraries are still great.
 
-### Why APIController in Django.
+I have designed the APIController in Django Ninja Extra to bring a more traditional controller-based approach to Django Ninja, providing more flexibility and adaptability to recent software design patterns. 
+If you prefer using class-based controls for building APIs, Django Ninja Extra's APIController is a great option for you.
 
-I come from a background where we model anything in class based object, and I have worked with many API tools out there in python: DRF, FastAPI, Flask-Restful. It is either function based or class tailored to function based.
-Don't get me wrong, there are still great libraries. In fact, some features of Django-Ninja-Extra came from DRF. So I am a big fan. I needed more.
+## ControllerBase
 
-I enjoyed Django ORM and I missed it while working with FastAPI but Django-Ninja became a saving grace. It brought FastAPI to Django in one piece. And it's super fast.
+The `ControllerBase` class is the base class for all controllers in Django Ninja Extra. 
+It provides the core functionality for handling requests, validating input, and returning responses in a class-based approach.
 
-So I designed APIController to extend Django-Ninja to class-based and have something more flexible to adapt to recent software design patterns out there.
+The class includes properties and methods that are common to all controllers, such as the `request` object, `permission_classes`, and `response` object which are part of the `RouteContext`. 
+The request object contains information about the incoming request, such as headers, query parameters, and body data. 
+The permission_classes property is used to define the permissions required to access the controller's routes, 
+while the response object is used to construct the final response that is returned to the client.
 
-So if you enjoy class-based controls for building API, welcome aboard.
+In addition to the core properties, the `ControllerBase` class also includes a number of utility methods that can be used to handle common tasks such as object permission checking (`check_object_permission`), creating quick responses (`create_response`), and fetching data from database (`get_object_or_exception`). 
+These methods can be overridden in subclasses to provide custom behavior.
 
-## ControllerBase
+The ControllerBase class also includes a **dependency injection** system that allows for easy access to other services and objects within the application, such as the repository services etc.
 
 ```python
-class ControllerBase(ABC):
+from ninja_extra import ControllerBase, api_controller
+
+@api_controller('/users')
+class UserControllerBase(ControllerBase):
     ...
 ```
 
-APIController decorates any class with `ControllerBase` if its not inheriting from it.
+
+## APIController Decorator
+The `api_controller` decorator is used to define a class-based controller in Django Ninja Extra. 
+It is applied to a ControllerBase class and takes several arguments to configure the routes and functionality of the controller.
+
+The first argument, `prefix_or_class`, is either a prefix string for grouping all routes registered under the controller or the class object that the decorator is applied on.
+
+The second argument, `auth`, is a list of all Django Ninja Auth classes that should be applied to the controller's routes.
+
+The third argument, `tags`, is a list of strings for OPENAPI tags purposes.
+
+The fourth argument, `permissions`, is a list of all permissions that should be applied to the controller's routes.
+
+The fifth argument, `auto_import`, defaults to true, which automatically adds your controller to auto import list.
+
+for example:
+
+```python
+import typing
+from ninja_extra import api_controller, ControllerBase, permissions, route
+from django.contrib.auth.models import User
+from ninja.security import APIKeyQuery
+from ninja import ModelSchema
+
+
+class UserSchema(ModelSchema):
+    class Config:
+        model = User
+        model_fields = ['username', 'email', 'first_name']
+
+
+@api_controller('users/', auth=[APIKeyQuery()], permissions=[permissions.IsAuthenticated])
+class UsersController(ControllerBase):
+    @route.get('', response={200: typing.List[UserSchema]})
+    def get_users(self):
+        # Logic to handle GET request to the /users endpoint
+        users = User.objects.all()
+        return users
+
+    @route.post('create/', response={200: UserSchema})
+    def create_user(self, payload: UserSchema):
+        # Logic to handle POST request to the /users endpoint
+        new_user = User.objects.create(
+            username=payload.username,
+            email=payload.email,
+            first_name=payload.first_name,
+        )
+        new_user.set_password('password')
+        return new_user
+
+```
+
+In the above code, we have defined a controller called `UsersController` using the `api_controller` decorator. 
+The decorator is applied to the class and takes two arguments, the URL endpoint `/users` and `auth` and `permission` classes. 
+And `get_users` and `create_user` are route function that handles GET `/users` and POST `/users/create` incoming request.
+
 
 !!!info
-Inheriting from ControllerBase class gives you more IDE intellisense support.
+    Inheriting from ControllerBase class gives you more IDE intellisense support.
 
 ## Quick Example
 
-Let's create an APIController to manage Django user model
+Let's create an APIController to properly manage Django user model
 
 ```python
 import uuid
@@ -79,3 +144,25 @@ class UsersController(ControllerBase):
         user = self.get_object_or_exception(self.user_model, id=user_id)
         return user
 ```
+
+In the example above, the `UsersController` class defines several methods that correspond to different HTTP methods, 
+such as `create_user`, `update_user`, `delete_user`, `list_user` and `get_user_by_id`. 
+These methods are decorated with `http_post`, `http_generic`, `http_delete`, `http_get` decorators respectively.
+
+The `create_user` method uses `http_post` decorator and accepts a user argument of type `UserSchema`, 
+which is a `ModelSchema` that is used to validate and serialize the input data. 
+The method is used to create a new user in the system and return an `ID` of the user.
+
+The `update_user` method uses `http_generic` decorator and accepts a `user_id` argument of type int. 
+The decorator is configured to handle both `PUT` and `PATCH` methods and 
+provides a response argument of type `UserSchema` which will be used to serialize the user object.
+
+The `delete_user` method uses `http_delete` decorator and accepts a `user_id` argument of type int and a response argument of type 
+Detail which will be used to return a 204 status code with an empty body on success.
+
+The `list_user` method uses `http_get` decorator and decorated with `pagination.paginate` decorator that paginate the results of the method using `PageNumberPaginationExtra` class with page_size=50. 
+It also provides a response argument of type `pagination.PaginatedResponseSchema[UserSchema]` which will be used to serialize and paginate the list of users returned by the method.
+
+The `get_user_by_id` method uses `http_get` decorator and accepts a `user_id` argument of type int and a response argument of type UserSchema which will be used to serialize the user object.
+
+The UsersController also use `self.get_object_or_exception(self.user_model, id=user_id)` which is a helper method that will raise an exception if the user object is not found.

docs/index.md

@@ -8,8 +8,8 @@
 
 # Django Ninja Extra
 
-**Django Ninja Extra** is a complete class-based fashion of building and setting up APIs at incredible speed with incredible performance.
-It utilizes [**Django Ninja**](https://django-ninja.rest-framework.com) core features without compromising speed.
+The **Django Ninja Extra** package offers a convenient, **class-based** approach to quickly building and configuring high-performance APIs. 
+Utilizing the core features of [**Django Ninja**](https://django-ninja.rest-framework.com), it allows for speedy development without sacrificing performance."
 
 **Key features:**
 
@@ -35,9 +35,6 @@ Plus **Extra**:
 - pydantic >= 1.6 
 - Django-Ninja >= 0.16.1
 
-## Django-Ninja Benchmark
-**Django-Ninja-Extra** uses **Django-Ninja** under the hood, it can be assumed that Django-Ninja-Extra has the same benchmark with Django-Ninja
-![Django Ninja REST Framework](images/benchmark.png)
 
 Full documentation, [visit](https://eadwincode.github.io/django-ninja-extra/).
 

docs/route_context.md

@@ -0,0 +1,139 @@
+**Django Ninja Extra** provides the RouteContext object, which is available throughout the request lifecycle. 
+This object holds essential properties for the route handler that will handle the request. 
+These properties include the Django `HttpRequest` object, a list of permission classes for the route handler, 
+a temporary response object used by Django-Ninja to construct the final response, 
+and kwargs and args required for calling the route function. 
+
+It's important to note that these properties are not set at the beginning of the request, 
+but rather become available as the request progresses through different stages, 
+and before it reaches the route function execution.
+
+
+```python
+from pydantic import BaseModel as PydanticModel, Field
+
+class RouteContext(PydanticModel):
+    """
+    APIController Context which will be available to the class instance when handling request
+    """
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    permission_classes: PermissionType = Field([])
+    request: Union[Any, HttpRequest, None] = None
+    response: Union[Any, HttpResponse, None] = None
+    args: List[Any] = Field([])
+    kwargs: DictStrAny = Field({})
+```
+
+## How to Access `RouteContext`
+
+In Django Ninja Extra, the `RouteContext` object can be accessed within the **controller class** by using the `self.context` property. 
+This property is available at the instance level of the controller class, making it easy to access the properties and methods of the `RouteContext` object.
+
+For example.
+```python
+from ninja_extra import ControllerBase, api_controller, route
+from django.db import transaction
+from ninja_extra.permissions import IsAuthenticated
+from ninja_jwt.authentication import JWTAuth
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+
+@api_controller("/books", auth=JWTAuth(), permissions=[IsAuthenticated])
+class StoryBookSubscribeController(ControllerBase):
+    @route.get(
+        "/context",
+        url_name="subscribe",
+    )
+    @transaction.atomic
+    def subscribe(self):
+        user = self.context.request.user
+        return {'message': 'Authenticated User From context', 'email': user.email}
+    
+    @route.post(
+        "/context",
+        url_name="subscribe",
+    )
+    @transaction.atomic
+    def subscribe_with_response_change(self):
+        res = self.context.response
+        res.headers.setdefault('x-custom-header', 'welcome to custom header in response')
+        return {'message': 'Authenticated User From context and Response header modified', 'email': self.context.request.user.email}
+
+```
+
+In the example, we can access the authenticated `user` object from the request object in the `self.context` property, which is available in the controller class. 
+This allows us to easily access the authenticated user's information
+
+### Modifying Response Header with RouteContext
+
+The `RouteContext` object provides you with the necessary properties and methods to manipulate the response data before it is returned to the client.
+With the RouteContext object, you can easily modify header, status, or cookie data for the response returned for a specific request
+
+For example, lets add extra `header` info our new endpoint, `subscribe_with_response_change` as shown below.
+```python
+from ninja_extra import ControllerBase, api_controller, route
+from django.db import transaction
+from ninja_extra.permissions import IsAuthenticated
+from ninja_jwt.authentication import JWTAuth
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+
+@api_controller("/books", auth=JWTAuth(), permissions=[IsAuthenticated])
+class StoryBookSubscribeController(ControllerBase):
+    @route.post(
+        "/context-response",
+        url_name="response",
+    )
+    @transaction.atomic
+    def subscribe_with_response_change(self):
+        res = self.context.response
+        res.headers['x-custom-header'] = 'welcome to custom header in response'
+        return {'message': 'Authenticated User From context and Response header modified', 'email': self.context.request.user.email}
+
+```
+
+## Using `RouteContext` in Schema
+
+There may be situations where you need to access the request object during schema validation. 
+Django Ninja Extra makes this easy by providing a way to resolve the `RouteContext` object during the request, 
+which can then be used to access the request object and any other necessary properties. 
+This allows you to use the context of the request within the validation process, making it more flexible and powerful.
+
+For example:
+
+```python
+from typing import Optional
+from django.urls import reverse
+from ninja_extra import service_resolver
+from ninja_extra.controllers import RouteContext
+from ninja import ModelSchema
+from pydantic import AnyHttpUrl, validator
+
+
+class StoreBookSchema(ModelSchema):
+    borrowed_by: Optional[UserRetrieveSchema]
+    store: AnyHttpUrl
+    book: BookSchema
+
+    class Config:
+        model = StoreBook
+        model_fields = ['borrowed_by', 'store', 'book']
+
+    @validator("store", pre=True, check_fields=False)
+    def store_validate(cls, value_data):
+        context: RouteContext = service_resolver(RouteContext)
+        value = reverse("store:detail", kwargs=dict(store_id=value_data.id))
+        return context.request.build_absolute_uri(value)
+```
+
+In the example above, we used the `service_resolver`, a dependency injection utility function, to resolve the `RouteContext` object. 
+This gave us access to the request object, which we used to construct a full URL for our store details. 
+By using the `service_resolver` to access the RouteContext, we can easily access the request object, 
+and use it to gather any necessary information during the validation process.