Metadata-Version: 2.4
Name: django-api-readme
Version: 0.2.0
Summary: Generate clean API Markdown documentation natively from Django URLs and DRF serializers.
Author: CodeWithClinton
License: MIT
Project-URL: Homepage, https://github.com/CodeWithClinton/django-api-readme
Project-URL: Repository, https://github.com/CodeWithClinton/django-api-readme.git
Project-URL: Bug Tracker, https://github.com/CodeWithClinton/django-api-readme/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14.0; extra == "drf"
Dynamic: license-file

# 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**
```bash
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**
```bash
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`:
```python
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!
```markdown
<!-- 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:
```bash
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:

```python
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:

```python
@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):

```python
@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:

```python
@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

```json
{
  "error": "Wrong password"
}
```

---

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