🗡️
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!
11 Dec 03, 2022
2 Jun 27, 2022
1 Feb 07, 2022
1 Dec 18, 2021
25 Dec 26, 2022
34 Dec 30, 2022
12 Oct 30, 2022
4 Dec 14, 2022
6 Oct 06, 2022
261 Jan 03, 2023
123 Jan 06, 2023
136 Jan 06, 2023
2 Jan 04, 2022
5 May 03, 2022
0 Feb 01, 2022
31 Nov 29, 2022
241 Jan 01, 2023
1 Nov 01, 2021
101 Oct 30, 2022
10 Dec 27, 2022