Metadata-Version: 2.4
Name: drf-routes
Version: 0.1.1
Summary: A management command to list all Django REST Framework routes — like `rails routes` for Django.
Author-email: Shibin <shibi393493@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/shibinshibii/drf-routes
Project-URL: Repository, https://github.com/shibinshibii/drf-routes
Project-URL: Issues, https://github.com/shibinshibii/drf-routes/issues
Keywords: django,drf,djangorestframework,routes,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: djangorestframework>=3.12
Provides-Extra: pretty
Requires-Dist: rich>=13.0; extra == "pretty"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: rich>=13.0; extra == "dev"
Dynamic: license-file

# drf-routes

**Zero-config API documentation generator for Django REST Framework.**

One command. No YAML. No decorators. No OpenAPI schema maintenance.  
Just point it at your existing Django project and get a full API reference — automatically.

```bash
pip install drf-routes
python manage.py routes --format markdown
# → api_docs.md generated. Done.
```

> Like `rails routes`, but for Django. With full API docs.

---

## 🚀 In 10 Seconds

```bash
# 1. Install
pip install drf-routes

# 2. Add to INSTALLED_APPS (one line)
# "drf_routes"

# 3. Generate your full API reference
python manage.py routes --format markdown
```

That's it. Open `api_docs.md` — your entire API is documented.  
Serializers, permissions, auth classes, filters, path params, docstrings — all extracted automatically from your existing views. No annotations. No config files. No extra code.

---

## 🆚 How It Compares

| Feature | Swagger / drf-yasg | drf-spectacular | **drf-routes** |
|---|---|---|---|
| Setup complexity | Heavy (OpenAPI schema config) | Medium (schema hooks) | **Zero** |
| Annotations required | Yes (`@swagger_auto_schema`) | Yes (`@extend_schema`) | **No** |
| Works on existing projects | Partial | Partial | **Yes, out of the box** |
| Terminal route table | ❌ | ❌ | ✅ |
| Per-app doc generation | ❌ | ❌ | ✅ |
| JSON output | ❌ | ❌ | ✅ |
| Markdown docs | ❌ | ❌ | ✅ |
| Interactive UI | ✅ | ✅ | ❌ (roadmap) |

**The tradeoff:** drf-routes doesn't generate interactive Swagger UI — it generates clean, portable Markdown that lives in your repo. Use it for internal docs, quick audits, and onboarding — without the Swagger maintenance burden.

---

## 📦 Install

```bash
pip install drf-routes
```

For colored terminal output (recommended):

```bash
pip install drf-routes[pretty]
```

Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    "drf_routes",
]
```

---

## 📋 Terminal Route Table

```bash
python manage.py routes
```

```
╭──────────────────────────────────────────────────────────────────────────────────────────╮
│ DRF Route Map                                                                            │
├────────────────────────┬──────────────────────┬──────────────────┬─────────────────┬────┤
│ URL                    │ Methods              │ View             │ Serializer      │ Name│
├────────────────────────┼──────────────────────┼──────────────────┼─────────────────┼────┤
│ /api/users/            │ GET POST             │ UserViewSet      │ UserSerializer  │ …  │
│ /api/users/{id}/       │ GET PUT PATCH DELETE │ UserViewSet      │ UserSerializer  │ …  │
│ /api/posts/            │ GET POST             │ PostViewSet      │ PostSerializer  │ …  │
│ /api/auth/login/       │ POST                 │ LoginView        │ —               │ …  │
│ /health/               │ —                    │ health_check     │ —               │ …  │
╰────────────────────────┴──────────────────────┴──────────────────┴─────────────────┴────╯
```

---

## 📝 Generated API Reference (Markdown)

Running `--format markdown` produces a complete `api_docs.md` with:

- **Cover page** — timestamp, total route count, method breakdown summary  
- **Table of contents** — per app, per endpoint with anchor links  
- **Per-endpoint sections** including:
  - Method badges (🟢 `GET`, 🔵 `POST`, 🔴 `DELETE`, etc.)
  - **Request Schema** — Detailed field types, required status, and validation rules (min/max, choices).
  - **Query Parameters** — Search, ordering, filtering (`filterset_fields`/`class`), and pagination controls.
  - **Response Examples** — Mock JSON payloads for success and collapsible sections for common error states (400, 401, 403).
  - **Access Control** — Summaries and source code logic for custom permissions.
  - Path parameters table (`{id}`, `{pk}`, etc.)
  - Authentication classes & Filter backends
  - Docstring (extracted from the view class, skipping generic framework boilerplate)
- **Appendix** — flat table of all routes

All metadata is extracted **automatically** from your existing views. **Zero annotations needed.**

### Example endpoint output

```markdown
### `/api/users/{id}/`

🔷 **DRF**  |  **View:** `UserDetailView`  |  **Module:** `users.views`

**Methods**

🟢 `GET`  🟡 `PUT`  🟠 `PATCH`  🔴 `DELETE`

**Path Parameters**

| Parameter | Type   |
|-----------|--------|
| `{id}`    | string |

**Details**

| Field           | Value               |
|-----------------|---------------------|
| URL Name        | `user-detail`       |
| Serializer      | `UserSerializer`    |
| Permissions     | `IsAuthenticated`   |
| Authentication  | `JWTAuthentication` |
| Search Fields   | `username` `email`  |
```

---

## 🔧 Usage

```bash
# List all routes (rich table in terminal)
python manage.py routes

# Filter by app
python manage.py routes --app users

# Search by URL or view name
python manage.py routes --search login

# JSON output (pipe-friendly)
python manage.py routes --format json

# Generate a Markdown API reference (saved to api_docs.md)
python manage.py routes --format markdown

# Markdown with a custom output path
python manage.py routes --format markdown --output docs/api.md

# Generate a separate api_docs.md inside EACH app directory
python manage.py routes --format markdown --per-app

# Per-app docs, filtered to a specific app
python manage.py routes --format markdown --per-app --app users

# Custom project name in the doc title
python manage.py routes --format markdown --project-name "My API"

# Include Django admin routes (hidden by default)
python manage.py routes --include-admin

# Disable color
python manage.py routes --no-color
```

---

## ⚙️ Options

| Flag | Description |
|---|---|
| `--app <name>` | Filter by Django app name or module |
| `--search <term>` | Search by URL, view name, or route name (case-insensitive) |
| `--format table\|json\|markdown` | Output format (default: `table`) |
| `--output <file>` | Write output to a file (auto-defaults to `api_docs.md` for markdown) |
| `--per-app` | Generate a separate `api_docs.md` inside each Django app directory |
| `--project-name <name>` | Project name used in the markdown document title |
| `--include-admin` | Show Django admin routes |
| `--no-color` | Disable colored output |

---

## 🔍 What It Detects

| Feature | DRF `ViewSet` | DRF `APIView` | Django Views |
|---|---|---|---|
| **Methods** | ✅ Automatic | ✅ From handlers | ✅ `http_method_names` |
| **Serializers** | ✅ `serializer_class` | ✅ **Smart discovery** | — |
| **Request Schema** | ✅ Field-level | ✅ Field-level | — |
| **Permissions** | ✅ **With logic** | ✅ **With logic** | — |
| **Filters/Query** | ✅ Extensive | ✅ Extensive | — |
| **Examples** | ✅ Mock JSON | ✅ Mock JSON | — |

**Smart Discovery for APIView:** Even if you don't use `serializer_class` (common in raw `APIView` subclasses), `drf-routes` will statically analyze your `post`/`put`/`patch` methods to find used serializers and document their fields automatically.

---

## 📤 JSON Output

```bash
python manage.py routes --format json | jq '.[0]'
```

```json
{
  "url": "/api/users/",
  "name": "user-list",
  "view": "UserViewSet",
  "module": "myapp.views",
  "methods": ["GET", "POST"],
  "serializer": "UserSerializer",
  "app": "users",
  "is_drf": true
}
```

Pipe into `jq`, scripts, CI pipelines — whatever you need.

---

## ✅ Tests

The package ships with a test suite covering route resolution, view inspection, and Markdown formatting:

```bash
pip install drf-routes[dev]
pytest
```

Tests use `pytest-django` and run against a minimal in-memory Django project — no external services needed.

---

## 📋 Requirements

- Python ≥ 3.9
- Django ≥ 3.2
- djangorestframework ≥ 3.12
- `rich` ≥ 13.0 *(optional, for colored table output)*

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide — setup, branch naming, commit style, PR checklist, and how to report bugs.

---

## License

MIT
