django-api-readme 0.2.0

Generate clean API Markdown documentation natively from Django URLs and DRF serializers.

django-api-readme

A production-ready Python package that natively integrates with Django and Django REST Framework (DRF) to automatically discover and map your API routes into clean, structured Markdown documentation.

It reads your configuration dynamically and supports optional payload inspection for DRF serializers without any hard dependencies.

Installation

There are two ways to install this package depending on your environment:

1. Standard Installation

pip install django-api-readme

Use this if you are either NOT using Django REST Framework (DRF), OR if you already have DRF installed in your active project. (If DRF is already present, our package securely detects it at runtime and beautifully documents your endpoints automatically!)

2. Installation alongside DRF

pip install django-api-readme[drf]

Use this strictly as a shortcut if you are building an API inside a completely blank space and want pip to automatically download and install djangorestframework for you seamlessly alongside this package.

Usage

1. Register the Application
Add django_api_readme to your INSTALLED_APPS inside settings.py:

INSTALLED_APPS = [
    # ...
    'django_api_readme',
]

2. Insert the Markers
Add the following template boundaries into your target Markdown file (e.g., README.md). The generator will safely inject the documentation directly between them!

<!-- API_DOCS_START -->
<!-- API_DOCS_END -->

3. Run the Generator
Execute the native management command from your terminal to scan your codebase and overwrite the marker bounds automatically:

python manage.py generate_api_docs --output README.md --include /api/

Command Breakdown:

• generate_api_docs: Invokes the custom Django management command bundled with this package.
• --output README.md: (Optional) Specifies the target Markdown file where the API documentation bounds will be injected. Defaults to README.md.
• --include /api/: (Optional) Filters the discovered URLs so that only endpoints starting with /api/ are documented. This gracefully ignores admin panels or frontend routing!

---

The @api_doc Decorator

Use the @api_doc decorator to tell the generator what your request and response payloads look like. It accepts two positional arguments: the request body and the response body.

Without Serializers (Plain Dict)

If your views pull fields directly from request.data without a serializer, just pass a dictionary:

from rest_framework.decorators import api_view
from django_api_readme.decorators import api_doc

@api_doc({"username": "string", "password": "string"})
@api_view(['POST'])
def login_user(request):
    """Login with credentials.
    Authenticates a user and returns an access token.
    """
    username = request.data.get("username")
    password = request.data.get("password")
    ...

All dict fields default to required. The summary and description are automatically extracted from the docstring.

With Serializers

If you use DRF serializers, just pass them directly:

@api_doc(RegisterSerializer, UserSerializer)
@api_view(['POST'])
def register_user(request):
    """Register a new user."""
    ...

Mixing Dict and Serializer

You can freely mix — use a dict for the request and a serializer for the response (or vice versa):

@api_doc({"username": "string", "password": "string"}, UserSerializer)

Note: For Class-Based Views that already have serializer_class, the request body is inferred automatically — no decorator needed at all.

Advanced Usage

For endpoints that need query parameters or multiple response codes:

@api_doc(
    {"username": "string", "password": "string"},
    responses={
        200: {"token": "string", "user_id": "integer"},
        401: {"description": "Invalid credentials", "example": {"error": "Wrong password"}}
    },
    query_params=[
        {"name": "remember", "type": "boolean", "required": False, "description": "Stay logged in."}
    ]
)

Parameter Reference

Parameter	Type	Description
1st positional	dict, list, or Serializer	Request body fields. Dict form: {"field": "type"}.
2nd positional	dict, list, or Serializer	Response body (auto-mapped to status 200).
summary	str	Overrides the docstring-derived summary.
description	str	Overrides the docstring-derived description.
responses	dict	Maps status codes to a Serializer, field dict, or {"description": ..., "example": ...}.
query_params	list[dict]	URL query parameters with name, type, required, description.

---

Example Output

This is a live example of the documentation the management command generates:

POST /api/auth/login/

Login with credentials.

Authenticates a user and returns an access token.

• View: login_user | Name: login

Query Parameters

Parameter	Type	Required	Description
remember	boolean	No	Stay logged in.

Request Body

Field	Type	Required	Description
username	string	Yes	-
password	string	Yes	-

Responses

200

Field	Type	Description
token	string	-
user_id	integer	-

401

Invalid credentials

{
  "error": "Wrong password"
}

---