^ Please read ^
Fast to learn, fast to code, fast to run
  [](https://badge.fury.io/py/django-ninja) [](https://pepy.tech/project/django-ninja) # Django Ninja - Fast Django REST Framework **Django Ninja** is a web framework for building APIs with **Django** and Python 3.6+ **type hints**. **Key features:** - **Easy**: Designed to be easy to use and intuitive. - **FAST execution**: Very high performance thanks to **Pydantic** and **async support**. - **Fast to code**: Type hints and automatic docs lets you focus only on business logic. - **Standards-based**: Based on the open standards for APIs: **OpenAPI** (previously known as Swagger) and **JSON Schema**. - **Django friendly**: (obviously) has good integration with the Django core and ORM. - **Production ready**: Used by multiple companies on live projects (If you use django-ninja and would like to publish your feedback, please email ppr.vitaly@gmail.com).  **Documentation**: https://django-ninja.dev --- ## Installation ``` pip install django-ninja ``` ## Usage In your django project next to urls.py create new `api.py` file: ```Python from ninja import NinjaAPI api = NinjaAPI() @api.get("/add") def add(request, a: int, b: int): return {"result": a + b} ``` Now go to `urls.py` and add the following: ```Python hl_lines="3 7" ... from .api import api urlpatterns = [ path("admin/", admin.site.urls), path("api/", api.urls), # <---------- ! ] ``` **That's it !** Now you've just created an API that: - receives an HTTP GET request at `/api/add` - takes, validates and type-casts GET parameters `a` and `b` - decodes the result to JSON - generates an OpenAPI schema for defined operation ### Interactive API docs Now go to http://127.0.0.1:8000/api/docs You will see the automatic interactive API documentation (provided by Swagger UI or Redoc):  ## Sponsorshttp://localhost:8000/api/example?d=1577836800 # same as 2020-01-01 http://localhost:8000/api/example?d=2020-01-01### Using Schema You can also use Schema to encapsulate GET parameters: ```python hl_lines="1 2 5 6 7 8" {!./src/tutorial/query/code010.py!} ``` For more complex filtering scenarios please refer to [filtering](./filtering.md). vitalik-django-ninja-0b67d47/docs/docs/guides/input/request-parsers.md 0000664 0000000 0000000 00000003276 15156602544 0026057 0 ustar 00root root 0000000 0000000 # Request parsers In most cases, the default content type for REST API's is JSON, but in case you need to work with other content types (like YAML, XML, CSV) or use faster JSON parsers, **Django Ninja** provides a `parser` configuration. ```python api = NinjaAPI(parser=MyYamlParser()) ``` To create your own parser, you need to extend the `ninja.parser.Parser` class, and override the `parse_body` method. ## Example YAML Parser Let's create our custom YAML parser: ```python hl_lines="4 8 9" import yaml from typing import List from ninja import NinjaAPI from ninja.parser import Parser class MyYamlParser(Parser): def parse_body(self, request): return yaml.safe_load(request.body) api = NinjaAPI(parser=MyYamlParser()) class Payload(Schema): ints: List[int] string: str f: float @api.post('/yaml') def operation(request, payload: Payload): return payload.dict() ``` If you now send YAML like this as the request body: ```YAML ints: - 0 - 1 string: hello f: 3.14 ``` it will be correctly parsed, and you should have JSON output like this: ```JSON { "ints": [ 0, 1 ], "string": "hello", "f": 3.14 } ``` ## Example ORJSON Parser [orjson](https://github.com/ijl/orjson#orjson) is a fast, accurate JSON library for Python. It benchmarks as the fastest Python library for JSON and is more accurate than the standard `json` library or other third-party libraries. ``` pip install orjson ``` Parser code: ```python hl_lines="1 8 9" import orjson from ninja import NinjaAPI from ninja.parser import Parser class ORJSONParser(Parser): def parse_body(self, request): return orjson.loads(request.body) api = NinjaAPI(parser=ORJSONParser()) ``` vitalik-django-ninja-0b67d47/docs/docs/guides/response/ 0000775 0000000 0000000 00000000000 15156602544 0023057 5 ustar 00root root 0000000 0000000 vitalik-django-ninja-0b67d47/docs/docs/guides/response/config-pydantic.md 0000664 0000000 0000000 00000003637 15156602544 0026470 0 ustar 00root root 0000000 0000000 # Overriding Pydantic Config There are many customizations available for a **Django Ninja `Schema`**, via the schema's [Pydantic `model_config`](https://docs.pydantic.dev/latest/api/config/). !!! info Under the hood **Django Ninja** uses [Pydantic Models](https://pydantic-docs.helpmanual.io/usage/models/) with all their power and benefits. The alias `Schema` was chosen to avoid confusion in code when using Django models, as Pydantic's model class is called Model by default, and conflicts with Django's Model class. ## Example Camel Case mode One interesting config attribute is [`alias_generator`](https://docs.pydantic.dev/latest/api/config/?query=alias_generator#pydantic.config.ConfigDict.alias_generator). Using Pydantic's example in **Django Ninja** can look something like: ```python hl_lines="10" from pydantic import ConfigDict from ninja import Schema def to_camel(string: str) -> str: words = string.split('_') return words[0].lower() + ''.join(word.capitalize() for word in words[1:]) class CamelModelSchema(Schema): model_config = ConfigDict(alias_generator=to_camel) str_field_name: str float_field_name: float ``` Keep in mind that when you want modify output for field names (like camel case) - you need to set as well `populate_by_name` and `by_alias` ```python hl_lines="6 14" from pydantic import ConfigDict class UserSchema(ModelSchema): model_config = ConfigDict( alias_generator = to_camel populate_by_name = True, # !!!!!! <-------- ) class Meta: model = User fields = ["id", "email", "is_staff"] @api.get("/users", response=list[UserSchema], by_alias=True) # !!!!!! <-------- by_alias def get_users(request): return User.objects.all() ``` results: ```JSON [ { "id": 1, "email": "tim@apple.com", "isStaff": true }, { "id": 2, "email": "sarah@smith.com", "isStaff": false } ... ] ``` vitalik-django-ninja-0b67d47/docs/docs/guides/response/django-pydantic-create-schema.md 0000664 0000000 0000000 00000005474 15156602544 0031165 0 ustar 00root root 0000000 0000000 # Using create_schema Under the hood, [`ModelSchema`](django-pydantic.md#modelschema) uses the `create_schema` function. This is a more advanced (and less safe) method - please use it carefully. ## `create_schema` **Django Ninja** comes with a helper function `create_schema`: ```python def create_schema( model, # django model name = "", # name for the generated class, if empty model names is used depth = 0, # if > 0 schema will also be created for the nested ForeignKeys and Many2Many (with the provided depth of lookup) fields: list[str] = None, # if passed - ONLY these fields will added to schema exclude: list[str] = None, # if passed - these fields will be excluded from schema optional_fields: list[str] | str = None, # if passed - these fields will not be required on schema (use '__all__' to mark ALL fields required) custom_fields: list[tuple(str, Any, Any)] = None, # if passed - this will override default field types (or add new fields) ) ``` Take this example: ```python hl_lines="2 4" from django.contrib.auth.models import User from ninja.orm import create_schema UserSchema = create_schema(User) # Will create schema like this: # # class UserSchema(Schema): # id: int # username: str # first_name: str # last_name: str # password: str # last_login: datetime # is_superuser: bool # email: str # ... and the rest ``` !!! Warning By default `create_schema` builds a schema with ALL model fields. This can lead to accidental unwanted data exposure (like hashed password, in the above example).