$ show vitalik/django-ninja
Django Ninja is a Python library that provides a FastAPI-inspired, type-hint-driven framework for building REST APIs on top of Django. It leverages Pydantic v2 for request validation and serialization, and automatically generates OpenAPI 3.0 schemas with interactive Swagger UI and Redoc documentation. The library offers a decorator-based API definition (e.g., @api.get, @router.post), supports sync and async views, and includes built-in support for authentication (API keys, HTTP Basic/Bearer, Django session), throttling, pagination (limit-offset, page-number, cursor), filtering (declarative FilterSchema), file uploads, streaming responses (SSE, JSONL), and CSRF protection. It integrates deeply with Django's ORM through ModelSchema and create_schema, and provides a TestClient for fast, serverless testing. The architecture is modular: NinjaAPI is the central application class, Router groups endpoints with nested routing and auth inheritance, and Operation handles the request lifecycle (auth, throttle, validation, response). The codebase is well-structured, extensively tested (100% coverage target), and actively maintained with broad compatibility across Python 3.7–3.14 and Django 3.1–6.1. It is a mature, production-ready framework used by multiple companies.
The LLM identified 4 files worth highlighting for reuse:
Provides a reusable pagination framework with a base class PaginationBase and concrete implementations (LimitOffsetPagination, PageNumberPagination, CursorPagination). Each paginator defines custom Input/Output schemas and an items_attribute for response structure. The @paginate decorator integrates seamlessly with NinjaAPI operations. This module is self-contained, depends only on standard library and Pydantic, and can be extracted for use in other frameworks or standalone projects.
Implements a set of authentication classes (APIKeyQuery, HttpBasicAuth, HttpBearer, SessionAuth) that follow a common base class pattern. Each class validates credentials from request parameters (query, header, cookie) and returns user info. The design allows easy extension for custom auth methods. The module is isolated, depends only on Django's request object and standard library, and can be reused in other Django projects or extracted as a standalone auth library.
Provides TestClient and TestAsyncClient classes that simulate HTTP requests against a NinjaAPI without running a server. They use Django's RequestFactory under the hood, handling path parameters, headers, and body serialization. The async variant uses Django's async request support. This is a clean, reusable testing utility that can be extracted for any Django project needing a lightweight API test client, not tied to Ninja-specific internals.
Implements FilterSchema, a declarative way to define query parameter filters for Django ORM. Uses FilterLookup annotations to specify field lookups (exact, contains, gt, etc.) and automatically generates a Pydantic schema for validation. The schema's to_queryset method applies filters to a QuerySet. This pattern is self-contained, demonstrates non-obvious skill in combining Pydantic with ORM filtering, and can be extracted for other ORM-based projects.