DRF'da avtomatik Swagger: hujjat kodning o'zidan tug'iladi

API yozayotgan odamning ishi endpoint bilan tugamaydi — uni kimdir ishlatishi kerak: mobil jamoa, frontendchi, ba'zan olti oydan keyingi o'zingiz. Va shu yerda abadiy savollar boshlanadi: qanday endpoint'lar bor, qaysi maydonlar majburiy, javob qanday ko'rinishda keladi. Buni qo'lda yozilgan hujjat bilan yechish mumkin, lekin qo'lda yozilgan hujjatning taqdiri ma'lum — u ikkinchi haftadayoq koddan orqada qoladi.

Netflix-uslub API loyihamda boshqa yo'lni tanlaganman va o'shandan beri hamma DRF loyihada shu turadi: hujjat kodning o'zidan yasaladi. Serializer'lar, view'lar, permission'lar allaqachon hamma ma'lumotni o'z ichida saqlaydi — uni chiroyli sahifaga aylantirib beradigan asbob esa drf-spectacular.

Sozlash: uch qadam#

uv add drf-spectacular

# config/settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "drf_spectacular",
]

REST_FRAMEWORK = {
    # DRF'ga sxemani kim yasashini aytamiz
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
}

SPECTACULAR_SETTINGS = {
    "TITLE": "Movies API",
    "DESCRIPTION": "Video-kontent katalogi: filmlar, janrlar, reytinglar.",
    "VERSION": "1.0.0",
    # hujjat sahifasining o'zida sxema fayli ko'rinmasin — toza UI
    "SERVE_INCLUDE_SCHEMA": False,
}

# config/urls.py
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    # ...
    # xom sxema (OpenAPI JSON/YAML) — asboblar shuni o'qiydi
    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
    # odamlar uchun interaktiv sahifa
    path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema")),
]

Shu uch qadam bo'ldi. Brauzerda /api/docs/ ni oching — barcha endpoint'laringiz, maydonlari va tiplari bilan ro'yxat bo'lib turibdi, har birini "Try it out" tugmasi bilan shu yerning o'zida sinab ko'rsa bo'ladi. Postman kolleksiyasini qo'lda yig'ib yurish shart emas.

Hujjat sifatini kod sifati belgilaydi#

Muhim tushuncha: drf-spectacular hech narsani "o'ylab topmaydi", u kodda borini ko'rsatadi. Demak hujjatni yaxshilashning yo'li ham kodni boyitishdan o'tadi. Uch odat katta farq qiladi.

Birinchisi — serializer maydonlariga help_text:

# apps/movies/serializers.py
class MovieSerializer(serializers.ModelSerializer):
    class Meta:
        model = Movie
        fields = ["id", "title", "year", "rating", "genre"]
        extra_kwargs = {
            "rating": {"help_text": "0 dan 10 gacha, bir xona aniqlikda"},
            "year": {"help_text": "Chiqarilgan yili, masalan 2019"},
        }

Bu matnlar Swagger sahifasida maydon tavsifi bo'lib chiqadi — va Django admin'da ham ko'rinadi, bir mehnatga ikki foyda.

Ikkinchisi — alohida holatlarni extend_schema bilan izohlash. Standart CRUD o'zi tushunarli chiqadi, lekin maxsus action'larga izoh kerak bo'ladi:

# apps/movies/views.py
from drf_spectacular.utils import extend_schema


class MovieViewSet(viewsets.ModelViewSet):
    queryset = Movie.objects.all()
    serializer_class = MovieSerializer

    @extend_schema(
        summary="Tavsiya etilgan filmlar",
        description="Foydalanuvchi reytinglariga qarab 10 ta film qaytaradi. "
        "Ro'yxat har soatda qayta hisoblanadi.",
        responses=MovieSerializer(many=True),
    )
    @action(detail=False)
    def recommended(self, request): ...

Uchinchisi — docstring odatlari: view klassining docstring'i ham sxemaga tushadi. Ya'ni kod o'qigan hamkasbingiz uchun yozgan izohingiz frontend jamoasi uchun hujjat bo'lib ham xizmat qiladi.

Kimga ochiq bo'lishi kerak?#

Bitta savolni ochiq muhokama qilgan ma'qul: hujjat sahifasi hammaga ko'rinsinmi? Ochiq, ommaviy API bo'lsa — albatta. Ichki loyihada esa /api/docs/ sahifasi API'ingizning to'liq xaritasi ekanini unutmang — begona ko'z uchun bu qimmatli razvedka. Bunday holatda sahifani login ortiga olib qo'ying:

# config/urls.py — faqat kirgan foydalanuvchilarga
from django.contrib.admin.views.decorators import staff_member_required

urlpatterns += [
    path("api/docs/", staff_member_required(SpectacularSwaggerView.as_view(url_name="schema"))),
]

Yakun#

Uchta URL va bitta sozlama bloki evaziga API'ingiz o'zini o'zi hujjatlaydigan bo'ldi: kod o'zgardi — hujjat o'zgardi, orada hech kim hech narsani qo'lda yangilamaydi. Sifatni oshirish ham tanish ishlar orqali: help_text, docstring, extend_schema. Hujjat endi alohida yuk emas, kod yozish odatining bir qismi.

Keyingi — juftlikning ikkinchi qismi: filtrlash va pagination — ro'yxat endpoint'ini «hammasini qaytaradigan»dan «keraklisini qaytaradigan»ga aylantirish.