🗡️
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!
16 Dec 21, 2022
3 Jul 14, 2022
3 Feb 17, 2022
1 Feb 10, 2022
60 Dec 15, 2022
0 Feb 26, 2022
19 Jun 03, 2021
322 Dec 30, 2022
36 Dec 01, 2022
26 Nov 24, 2022
72 Dec 12, 2022
1.3k Dec 28, 2022
3 Oct 27, 2022
2 Feb 14, 2022
18 Jul 20, 2022
20 Sep 16, 2022
3 May 31, 2022
1 Jan 10, 2022
1 Dec 31, 2021
1 Jun 14, 2022