🗡️
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!
1 Jan 07, 2022
6k Jan 06, 2023
76 Jan 04, 2023
69 Dec 23, 2022
30 Dec 29, 2022
7 Dec 14, 2022
2 Sep 28, 2022
59 Dec 27, 2022
6 Jul 14, 2022
14 Dec 09, 2022
71 Nov 09, 2022
336 Jan 02, 2023
1 May 05, 2022
6 May 16, 2022
1 Nov 21, 2021
1 Jan 07, 2022
106 Dec 22, 2022
88 Dec 25, 2022
83 Dec 14, 2022
1 Jan 22, 2022