repository·master·Indexed 43 days ago
https://github.com/pmdevita/django-shinobiA high-performance web framework for building APIs with Django, utilizing Python 3.6+ type hints and Pydantic for fast execution and automatic validation. It features automatic OpenAPI schema generation with Swagger UI and Redoc, async view support for Django 3.1+, and performance improvements for Schemas.
You can choose how the documentation's JavaScript and CSS assets are served:
ninja to your INSTALLED_APPS. The interactive UI will be hosted via a CDN."ninja" to your INSTALLED_APPS. This allows standard Django staticfiles mechanics to host the documentation assets from your own server.Django Ninja automatically determines the source of a function parameter based on its type and declaration:
/items/{item_id}).int, str, float, bool) and is not in the path.Schema (or Pydantic BaseModel).You can use all three types in a single path operation function.
from ninja import NinjaAPI, Schema
api = NinjaAPI()
class Item(Schema):
name: str
price: float
@api.put("/items/{item_id}")
def update_item(request, item_id: int, item: Item, query_param: str):
# item_id is from path
# item is from request body
# query_param is from query string
return {"item_id": item_id, "item": item, "query_param": query_param}Django Shinobi (via Django Ninja) automatically generates reverse URL names for each method decorated in a NinjaAPI instance or a Router.
By default, URLs are contained within a namespace that follows the pattern api-<version>. The URL name itself matches the name of the decorated function.
To resolve these URLs in your Django code, use reverse_lazy or reverse with the format namespace:url_name.
api = NinjaAPI()
@api.get("/")
def index(request):
...
# Resolving the URL
index_url = reverse_lazy("api-1.0.0:index")The depth argument allows create_schema to introspect Django model relationships such as ForeignKey, OneToOne, and ManyToManyField. Setting depth > 0 will cause the function to automatically generate schemas for the related models up to the specified depth.
from django.contrib.auth.models import User
from ninja.orm import create_schema
# depth=1 will introspect the 'groups' ManyToMany field
UserSchema = create_schema(User, depth=1, fields=['username', 'groups'])
# Resulting schema structure:
# class UserSchema(Schema):
# username: str
# groups: List[Group]
#
# class Group(Schema):
# id: int
# name: str
# permissions: List[int]To implement custom pagination logic, subclass ninja.pagination.PaginationBase (or AsyncPaginationBase for async support) and implement the following:
Input(Schema): A nested class defining the query parameters the paginator accepts.Output(Schema): A nested class defining the structure of the paginated response.paginate_queryset(self, queryset, pagination, **params): The method that performs the slicing/logic. It receives the queryset, the validated pagination input, and **params (which includes the request object).Note on Output Attributes: By default, items are placed in an 'items' key in the response. To change this, set the items_attribute string attribute on your class.
from ninja.pagination import paginate, PaginationBase
from ninja import Schema
from typing import List, Any
class CustomPagination(PaginationBase):
class Input(Schema):
skip: int
class Output(Schema):
items: List[Any]
total: int
per_page: int
# Change the key in the JSON response from 'items' to 'results'
items_attribute: str = "items"
def paginate_queryset(self, queryset, pagination: Input, **params):
skip = pagination.skip
return {
'items': queryset[skip : skip + 5],
'total': queryset.count(),
'per_page': 5,
}
@api.get('/users', response=List[UserSchema])
@paginate(CustomPagination)
def list_users(request):
return User.objects.all()Authentication in Django Ninja is defined at the operation level by passing an authentication object to the auth argument of an API decorator (e.g., @api.get(...)).
When an authentication object is used, the client must provide valid credentials (like a session cookie, API key, or Bearer token). If authentication fails, the API returns an HTTP 401 error. If successful, the return value of the authentication logic is assigned to the request.auth attribute, making it available within your endpoint function.
@api.get("/pets", auth=django_auth)
def pets(request):
# request.auth contains the authenticated user/object
return {"message": "success"}Django Shinobi (via Django Ninja) uses standard Python type hints to determine and validate input types. If no type hint is provided, a str is assumed. Providing explicit type hints allows the API to automatically validate and cast inputs (e.g., converting a query string value to an int).
@api.get("/math")
def math(request, a: int, b: int):
return {"add": a + b, "multiply": a * b}The project is planning a transition to version 1.0.0, which will introduce breaking changes to address architectural limitations. If you are currently using the library, be aware of the following planned changes that will require code updates:
auth): The authentication interface will transition from a callable to a class-based interface. This change is intended to provide native support for async authenticators.responses): The response handling will be expanded to support codes, headers, and content, bringing it closer to the behavior of a general Response class./. In v1, this behavior may change to allow the router prefix to act as a true prefix rather than a subfolder (avoiding forced slash joining in certain cases).While FastAPI is inspired by the same principles, Django Ninja is preferred for Django-based projects because it solves several integration friction points:
request instance attributes (similar to standard Django views), reducing boilerplate.model being used for both Django ORM models and Pydantic models in FastAPI/FastAPI-like environments.The auth argument can accept a list or tuple of authenticators. Django Ninja will attempt to authenticate using each one in order. If the first one fails, it moves to the second, and so on. If all provided authenticators fail, an authentication error is returned.
from ninja.security import APIKeyQuery, APIKeyHeader
# Tries Query first, then Header
@api.get("/multi", auth=[APIKeyQuery(), APIKeyHeader()])
def multi_auth_endpoint(request):
return {"auth": request.auth}When specifying a rate, use the format requests/time-unit. If the time unit is omitted, it defaults to seconds.
Supported units:
s or sec (seconds)m or min (minutes)h or hour (hours)d or day (days)Example: 100/5m, 100/300s, and 100/300 are all equivalent (100 requests per 5 minutes).
Django Ninja can simultaneously extract parameters from different sources in a single endpoint. It uses the type annotations to distinguish between them:
Form[...] are taken from the request form fields.