🗡️
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!
177 Dec 26, 2022
1 Nov 25, 2021
2 May 27, 2022
3 Apr 21, 2022
3.2k Jan 06, 2023
1 Nov 07, 2021
10 Dec 05, 2022
1 Dec 10, 2021
39 Nov 04, 2022
55 Sep 04, 2022
5 Nov 20, 2022
3 Oct 27, 2022
1 Jan 01, 2022
2 Jan 22, 2022
11 Jun 06, 2022
162 Dec 07, 2022
1 Feb 10, 2022
1 Feb 13, 2022
36 Dec 27, 2022
68 Nov 02, 2022