Какие знаешь способы автодокументирования кода в Django?

Способы автодокументирования кода в Django

Автодокументирование в Django — это мощный инструмент для создания и ведения документации API без необходимости её ручного обновления. Рассмотрю основные подходы, которые я использовал в боевых проектах.

1. Django REST Framework (DRF) + drf-spectacular

Самый популярный и современный способ для API. drf-spectacular генерирует OpenAPI 3.0 схему автоматически из код viewsets и serializers:

# settings.py
INSTALLED_APPS = [
    "drf_spectacular",
]

REST_FRAMEWORK = {
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "My API",
    "VERSION": "1.0.0",
    "SERVERS": [
        {"url": "https://api.example.com", "description": "Production"},
    ],
}

# views.py
from drf_spectacular.utils import extend_schema

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer

    @extend_schema(
        description="Получить список продуктов",
        parameters=[...],
        responses=ProductSerializer(many=True)
    )
    def list(self, request):
        return super().list(request)

Результат: автоматически генерируется Swagger/ReDoc UI по адресу /api/schema/swagger-ui/

2. docstrings + Sphinx

Для документирования Python кода используется Sphinx с расширениями:

def calculate_discount(price: float, discount_percent: float) -> float:
    """
    Вычисляет финальную цену со скидкой.
    
    Args:
        price: Исходная цена товара
        discount_percent: Размер скидки в процентах
    
    Returns:
        float: Финальная цена после применения скидки
    
    Raises:
        ValueError: Если скидка больше 100% или цена отрицательная
    
    Example:
        >>> calculate_discount(1000, 10)
        900.0
    """
    if not 0 <= discount_percent <= 100:
        raise ValueError("Скидка должна быть от 0 до 100%")
    return price * (1 - discount_percent / 100)

Sphinx генерирует HTML документацию, включая примеры использования.

3. Django Admin auto-documentation

Django Admin автоматически читает:

• verbose_name и verbose_name_plural модели
• help_text в полях
• list_display и list_filter

class Product(models.Model):
    name = models.CharField(
        max_length=200,
        verbose_name="Название продукта",
        help_text="Название должно быть уникальным"
    )
    price = models.DecimalField(
        max_digits=10,
        decimal_places=2,
        verbose_name="Цена",
        help_text="Укажите цену в рублях"
    )

    class Meta:
        verbose_name = "Продукт"
        verbose_name_plural = "Продукты"

4. Type hints + mypy

Python 3.5+ type hints служат документацией для IDE и mypy:

from typing import List, Optional

def get_products(
    category_id: int,
    limit: int = 10,
    offset: int = 0
) -> List[dict]:
    """Получить список продуктов по категории."""
    # IDE и mypy знают точные типы без docstring
    pass

5. Pydantic для валидации и схем

Pydantic моделей автоматически генерируют JSON Schema:

from pydantic import BaseModel, Field

class ProductSchema(BaseModel):
    id: int = Field(..., description="Уникальный ID продукта")
    name: str = Field(..., min_length=1, max_length=200)
    price: float = Field(..., gt=0, description="Цена в рублях")
    
    class Config:
        json_schema_extra = {
            "example": {
                "id": 1,
                "name": "iPhone 15",
                "price": 99999.99
            }
        }

6. MkDocs + docstrings

Интеграция docstring в MkDocs через mkdocstrings:

# mkdocs.yml
plugins:
  - search
  - mkdocstrings:
      default_handler: python

# API Reference

::: my_app.views.ProductViewSet
    options:
      show_source: true

7. GraphQL (если используешь)

GraphQL Schema сама по себе является документацией. Django GraphQL:

import graphene

class ProductType(graphene.ObjectType):
    id = graphene.Int(description="Уникальный ID")
    name = graphene.String(description="Название продукта")
    price = graphene.Float(description="Цена в рублях")

class Query(graphene.ObjectType):
    products = graphene.List(ProductType, description="Список всех продуктов")

GraphQL Playground автоматически показывает эту документацию.

Мой опыт и рекомендации

На практике я комбинирую эти подходы:

• DRF + drf-spectacular для REST API — быстро, стандартно, интегрируется с Swagger
• Type hints везде — помогают IDE и другим разработчикам
• Docstrings для сложной логики — бизнес-логика должна быть понятна
• Pydantic для внешних данных — валидация и документация в одном месте
• Django Admin help_text — внутренняя документация для конфигураций

Главное — не перегружай документацией простой очевидный код. Документируй:

• Публичные API
• Нетривиальную логику
• Причины архитектурных решений
• Как интегрироваться с системой