🗡️
Djagger
Automated OpenAPI documentation generator for Django. Djagger helps you generate a complete and comprehensive API documentation of your Django project by utilizing pydantic to create schema objects for your views.
Djagger is designed to be:
Quick start
Install using pip
pip install djagger
Add 'djagger' to your INSTALLED_APPS setting like this
INSTALLED_APPS = [
...
'djagger',
]
Include the djagger URLconf in your project urls.py like this if you want to use the built-in document views.
urlpatterns = [
...
path('djagger/', include('djagger.urls')),
]
Note that the path djagger/ is required when setting this URLconf. Feel free to remove djagger.urls when you are more comfortable and decide to customize your own documentation views. The routes provided here are for you to get started quickly.
Examples
In the examples, we alias pydantic BaseModel as Schema to avoid any confusion with Django's Model ORM objects. Django REST Framework views are used for the examples.
Example GET Endpoint
from rest_framework.views import APIView
from rest_framework.response import Response
from pydantic import BaseModel as Schema
class UserDetailsParams(Schema):
pk : int
class UserDetailsResponse(Schema):
""" GET response schema for user details
"""
first_name : str
last_name : str
age : int
email: str
class UserDetailsAPI(APIView):
""" Lists a given user's details.
Docstrings here will be used for the API's description in
the generated schema.
"""
get_path_params = UserDetailsParams
get_response_schema = UserDetailsResponse
def get(self, request, pk : int):
return Response({
"first_name":"John",
"last_name":"Doe",
"age": 30,
"email":"[email protected]"
})
Generated documentation
Example POST Endpoint
from pydantic import BaseModel as Schema, Field
from typing import Optional
from decimal import Decimal
class CreateItemRequest(Schema):
""" POST request body schema for creating an item.
"""
sku : str = Field(description="Unique identifier for an item")
name : str = Field(description="Name of an item")
price : Decimal = Field(description="Price of item in USD")
min_qty : int = 1
description : Optional[str]
class CreateItemResponse(Schema):
""" Post response schema for successful item creation.
"""
pk : int
details : str = Field(description="Details for the user")
class CreateItemAPI(APIView):
""" Endpoint to create an item.
"""
summary = "Create Item API Title" # Change title of API
post_body_params = CreateItemRequest
post_response_schema = CreateItemResponse
def post(self, request):
# Some code here...
return Response({
"pk":1,
"details":"Successfully created item."
})
Generated documentation
To include multiple responses for the above endpoint, for example, an error response code, create a new Schema for the error response and change the post_response_schema attribute to the following
class ErrorResponse(Schema):
""" Response schema for errors.
"""
status_code : int
details : str = Field(description="Error details for the user")
class CreateItemAPI(APIView):
""" API View to create an item.
"""
summary = "Create Item API Title" # Change title of API
post_body_params = CreateItemRequest
post_response_schema = {
"200": CreateItemResponse,
"400": ErrorResponse
}
def post(self, request):
...
Generated documentation
Documentation & Support
- Full documentation is currently a work in progress.
- This project is in continuous development. If you have any questions or would like to contribute, please email [email protected]
- If you want to support this project, do give it a
⭐ on github!
10 Mar 28, 2022
2 Dec 19, 2021
9 Sep 19, 2022
3 Nov 08, 2022
7 Feb 09, 2022
16 Nov 17, 2022
34 Sep 29, 2022
125 Dec 21, 2022
10.7k Jan 09, 2023
6 May 09, 2022
13 Oct 31, 2022
138 Jan 07, 2023
12 Dec 27, 2022
36 Dec 09, 2022
197 Nov 14, 2022
11 Oct 08, 2022
6 Nov 07, 2021
33 Dec 22, 2022
3 Nov 25, 2021
18.1k Jan 05, 2023