IlmHamroh
Python kursi/Web backend FastAPI16/16-dars16 daqiqa
Mundarija (23)

20.16-dars: Hujjatlar va OpenAPI

20-QISM — WEB-BACKEND (FastAPI) · 16-dars · 20-qism yakuni

1. Kirish va motivatsiya

API tayyor — endpointlar, auth, testlar. Lekin boshqalar uni qanday ishlatadi? Mijoz dasturchi qaysi endpoint bor, qanday parametr, qanday javob ekanini bilishi kerak. Buni qo'lda hujjatlash — sekin va tez eskiradi (kod o'zgaradi, hujjat qoladi). Yechim — avtomatik hujjatlar.

FastAPI'ning eng kuchli xususiyatlaridan biri — avtomatik interaktiv hujjatlar. Siz kodni (tip belgilari, Pydantic modellari, tavsiflar) yozasiz, FastAPI OpenAPI standartida hujjat yaratadi: /docs (interaktiv, sinab ko'rish mumkin) va /redoc. Hujjat har doim kodga mos (avtomatik yaratilgan). Bu — 20.5 dagi "yagona haqiqat manbai" ning natijasi.

Real vaziyat. Bir jamoa API hujjatini qo'lda (Word faylda) yozardi. Kod o'zgarsa, hujjat eskirardi — mijozlar noto'g'ri hujjatga qarab xato so'rov yuborardi. Yangi endpoint qo'shilsa, hujjat unutilardi. Jamoa FastAPI'ning avtomatik hujjatiga tayandi: /docsda har doim joriy API. Mijozlar /docsda sinab ko'radi, endpointni tushunadi. Hujjat yozish yo'qoldi (kod o'zi hujjat), va u hech qachon eskimaydi.

Bu darsda hujjatlar va OpenAPI'ni o'rganamiz va 20-qismni yakunlaymiz.

Bu darsda:

  • Avtomatik hujjatlar (/docs, /redoc)
  • OpenAPI sxemasi (/openapi.json)
  • Ilova metama'lumoti (title, description, version)
  • Endpoint tavsiflari (summary, description, tags)
  • Model va maydon tavsiflari
  • Misollar (examples)
  • Javob hujjatlari
  • 20-qism yakuni

ℹ Misollarda FastAPI TestClient bilan sinaladi.

2. Nazariya — chuqur tushuntirish

2.1. Avtomatik hujjatlar

FastAPI avtomatik interaktiv hujjat yaratadi:

Manzil Nima
/docs Swagger UI (interaktiv, sinab ko'rish)
/redoc ReDoc (o'qiladigan hujjat)
/openapi.json OpenAPI sxema (JSON)
python
app = FastAPI()
# /docs, /redoc, /openapi.json — avtomatik mavjud

Hujjatlar hech qanday qo'shimcha ishsiz yaratiladi — koddan (tip belgilari, modellar) olinadi. /docsda endpointlarni sinab ko'rish mumkin (bosib, so'rov yuborib). Hujjat har doim kodga mos.

2.2. OpenAPI sxemasi

OpenAPI — API'ni tavsiflovchi standart (JSON):

python
schema = app.openapi()      # yoki GET /openapi.json
# {"openapi": "3.1.0", "info": {...}, "paths": {...}, "components": {...}}
Bo'lim Nima
info Title, versiya, tavsif
paths Endpointlar (yo'l, metod, parametr)
components Modellar (sxemalar)

OpenAPI — standart, til-mustaqil API tavsifi. Undan hujjat (/docs), mijoz kodi (avtomatik generatsiya), test vositalari yaratiladi. FastAPI uni koddan avtomatik quradi.

2.3. Ilova metama'lumoti

FastAPI(...) — ilova haqida ma'lumot:

python
app = FastAPI(
    title="Wisar API",
    description="Kurslar platformasi API",
    version="1.0.0",
)

title, description, version — hujjat boshida ko'rinadi. version (20.5 — semantik versiyalash) API versiyasini bildiradi. Bu ma'lumot /docs va /openapi.jsonda chiqadi.

2.4. Endpoint tavsiflari

Har endpointga tavsif qo'shiladi:

python
@app.get(
    "/kurslar",
    summary="Kurslar ro'yxati",
    description="Barcha kurslarni sahifalash bilan qaytaradi",
    tags=["kurslar"],
)
def kurslar():
    ...
Parametr Vazifa
summary Qisqa nom
description Batafsil tavsif
tags Guruhlash (bo'lim)

summary va description — endpoint nima qilishini tushuntiradi. tags — endpointlarni guruhlaydi (/docsda bo'limlar). Docstring ham description bo'lib ishlatiladi.

2.5. Model va maydon tavsiflari

Pydantic model maydonlari ham hujjatlanadi (Field, 20.5):

python
from pydantic import BaseModel, Field

class Kurs(BaseModel):
    nom: str = Field(description="Kurs nomi", examples=["Python"])
    narx: float = Field(ge=0, description="Kurs narxi (so'mda)")

Field(description=..., examples=...) — maydon tavsifi va namuna. Bu /docsdagi so'rov/javob sxemasida ko'rinadi. Model o'zi sxema (20.5 — yagona manba).

2.6. Misollar (examples)

So'rov/javob uchun namunalar:

python
class Kurs(BaseModel):
    nom: str = Field(examples=["Python 3.14"])
    narx: float = Field(examples=[100.0])

examples — /docsda "Try it out" uchun namuna to'ldiradi. Mijoz dasturchi qanday ma'lumot yuborishni ko'radi. Yaxshi misol — hujjat sifatini oshiradi.

2.7. Javob hujjatlari

Turli javoblarni hujjatlash (responses):

python
@app.get(
    "/kurslar/{kurs_id}",
    responses={
        200: {"description": "Kurs topildi"},
        404: {"description": "Kurs topilmadi"},
    },
)
def kurs(kurs_id: int):
    ...

responses — turli status kodlar va ularning ma'nosini hujjatlaydi. response_model 20.5-bob muvaffaqiyatli javob shaklini beradi. Mijoz qanday javob kutishni biladi.

2.8. Hujjat — yagona manba natijasi

FastAPI hujjati koddan yaratiladi — bu 20.5 dagi "yagona haqiqat manbai":

Kod elementi Hujjatda
Tip belgisi Parametr turi
Pydantic model So'rov/javob sxemasi
Field(description) Maydon tavsifi
summary, tags Endpoint hujjati

Kod o'zgarsa, hujjat avtomatik yangilanadi — eskirmaydi. Bu FastAPI'ning kuchi: validatsiya, seriyalizatsiya va hujjat — bir manbadan (kod). Hujjatni alohida saqlash kerak emas.

3. Tez ma'lumotnoma

python
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(
    title="Wisar API",
    description="Kurslar platformasi",
    version="1.0.0",
)

class Kurs(BaseModel):
    nom: str = Field(description="Kurs nomi", examples=["Python"])
    narx: float = Field(ge=0, description="Narx")

@app.get("/kurslar", summary="Ro'yxat", tags=["kurslar"])
def kurslar(): ...

Hujjat manzillari

/docs        — Swagger UI (interaktiv)
/redoc       — ReDoc (o'qiladigan)
/openapi.json — OpenAPI sxema (JSON)

4. Batafsil misollar

Misollarda FastAPI TestClient bilan sinaladi.

Misol 1 — Avtomatik hujjatlar va OpenAPI sxema

python
"""avtomatik hujjatlar (/docs, /redoc); OpenAPI sxemasi (/openapi.json); ilova metama'lumoti (title, version)."""

import warnings
warnings.filterwarnings("ignore")

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI(
    title="Wisar API",
    description="Kurslar platformasi API",
    version="1.0.0",
)


@app.get("/kurslar")
def kurslar():
    return []


client = TestClient(app)


def main() -> None:
    print("=== 1. Interaktiv hujjatlar mavjud ===")
    print(f"  /docs → status {client.get('/docs').status_code} (Swagger UI)")
    print(f"  /redoc → status {client.get('/redoc').status_code} (ReDoc)")

    print("\n=== 2. OpenAPI sxemasi ===")
    schema = client.get("/openapi.json").json()
    print(f"  OpenAPI versiyasi: {schema['openapi']}")

    print("\n=== 3. Ilova metama'lumoti ===")
    print(f"  title: {schema['info']['title']}")
    print(f"  version: {schema['info']['version']}")
    print(f"  description: {schema['info']['description']}")

    print("\n=== 4. Endpointlar sxemada ===")
    print(f"  yo'llar: {sorted(schema['paths'].keys())}")
    print("  ⭐ /docs, /redoc, /openapi.json — avtomatik (kod'dan)")


if __name__ == "__main__":
    main()

Natijaning muhim qismi:

text
=== 1. Interaktiv hujjatlar mavjud ===
  /docs → status 200 (Swagger UI)
  /redoc → status 200 (ReDoc)

=== 2. OpenAPI sxemasi ===
  OpenAPI versiyasi: 3.1.0

=== 3. Ilova metama'lumoti ===
  title: Wisar API
  version: 1.0.0
  description: Kurslar platformasi API

=== 4. Endpointlar sxemada ===
  yo'llar: ['/kurslar']
  ⭐ /docs, /redoc, /openapi.json — avtomatik (kod'dan)

Nima ko'rsatdi: 2.1, 2.2, 2.3-bo'limlar.

Misol 2 — Endpoint va model tavsiflari

python
"""endpoint tavsiflari (summary, description, tags); model va maydon tavsiflari (Field description, examples); sxemada ko'rinishi."""

import warnings
warnings.filterwarnings("ignore")

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI(title="Wisar API", version="1.0.0")


class Kurs(BaseModel):
    nom: str = Field(description="Kurs nomi", examples=["Python 3.14"])
    narx: float = Field(ge=0, description="Kurs narxi")


@app.get("/kurslar", summary="Kurslar ro'yxati", description="Barcha kurslarni qaytaradi", tags=["kurslar"])
def kurslar():
    return []


@app.post("/kurslar", summary="Kurs yaratish", tags=["kurslar"], status_code=201)
def yarat(kurs: Kurs):
    return kurs


client = TestClient(app)


def main() -> None:
    schema = client.get("/openapi.json").json()

    print("=== 1. Endpoint summary va description ===")
    get_kurslar = schema["paths"]["/kurslar"]["get"]
    print(f"  summary: {get_kurslar['summary']}")
    print(f"  description: {get_kurslar['description']}")

    print("\n=== 2. Teglar (guruhlash) ===")
    print(f"  tags: {get_kurslar['tags']}")

    print("\n=== 3. Model sxemasi ===")
    kurs_schema = schema["components"]["schemas"]["Kurs"]
    print(f"  maydonlar: {sorted(kurs_schema['properties'].keys())}")

    print("\n=== 4. Maydon tavsifi va misoli ===")
    nom = kurs_schema["properties"]["nom"]
    print(f"  nom.description: {nom['description']}")
    print(f"  nom.examples: {nom.get('examples')}")
    print("  ⭐ summary/description/tags + Field(description, examples) — hujjat")


if __name__ == "__main__":
    main()

Natijaning muhim qismi:

text
=== 1. Endpoint summary va description ===
  summary: Kurslar ro'yxati
  description: Barcha kurslarni qaytaradi

=== 2. Teglar (guruhlash) ===
  tags: ['kurslar']

=== 3. Model sxemasi ===
  maydonlar: ['narx', 'nom']

=== 4. Maydon tavsifi va misoli ===
  nom.description: Kurs nomi
  nom.examples: ['Python 3.14']
  ⭐ summary/description/tags + Field(description, examples) — hujjat

Nima ko'rsatdi: 2.4, 2.5, 2.6-bo'limlar.

Misol 3 — Javob hujjatlari va response_model

python
"""response_model (javob sxemasi); responses (turli status hujjati); javob shakli hujjatda; tag metama'lumoti."""

import warnings
warnings.filterwarnings("ignore")

from fastapi import FastAPI, HTTPException
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI(title="Wisar API", version="1.0.0")

BAZA = {1: "Python"}


class KursJavob(BaseModel):
    id: int = Field(description="Kurs identifikatori")
    nom: str = Field(description="Kurs nomi")


@app.get(
    "/kurslar/{kurs_id}",
    response_model=KursJavob,
    summary="Bitta kurs",
    tags=["kurslar"],
    responses={
        200: {"description": "Kurs topildi"},
        404: {"description": "Kurs topilmadi"},
    },
)
def kurs(kurs_id: int):
    if kurs_id not in BAZA:
        raise HTTPException(status_code=404, detail="topilmadi")
    return {"id": kurs_id, "nom": BAZA[kurs_id]}


client = TestClient(app)


def main() -> None:
    schema = client.get("/openapi.json").json()
    endpoint = schema["paths"]["/kurslar/{kurs_id}"]["get"]

    print("=== 1. Javob status kodlari hujjatda ===")
    print(f"  hujjatlangan javoblar: {sorted(endpoint['responses'].keys())}")

    print("\n=== 2. Javob tavsiflari ===")
    print(f"  200: {endpoint['responses']['200']['description']}")
    print(f"  404: {endpoint['responses']['404']['description']}")

    print("\n=== 3. response_model sxemada ===")
    print(f"  KursJavob maydonlari: {sorted(schema['components']['schemas']['KursJavob']['properties'].keys())}")

    print("\n=== 4. Haqiqiy javob mos keladi ===")
    print(f"  /kurslar/1 → {client.get('/kurslar/1').json()}")
    print(f"  /kurslar/999 → status {client.get('/kurslar/999').status_code}")
    print("  ⭐ response_model + responses — javob shakli va status hujjati")


if __name__ == "__main__":
    main()

Natijaning muhim qismi:

text
=== 1. Javob status kodlari hujjatda ===
  hujjatlangan javoblar: ['200', '404', '422']

=== 2. Javob tavsiflari ===
  200: Kurs topildi
  404: Kurs topilmadi

=== 3. response_model sxemada ===
  KursJavob maydonlari: ['id', 'nom']

=== 4. Haqiqiy javob mos keladi ===
  /kurslar/1 → {'id': 1, 'nom': 'Python'}
  /kurslar/999 → status 404
  ⭐ response_model + responses — javob shakli va status hujjati

Nima ko'rsatdi: 2.5, 2.7, 2.8-bo'limlar.

Misol 4 — Amaliy: to'liq hujjatlangan API

Barcha hujjat elementlarini birlashtirgan API: metama'lumot, teglar bilan guruhlangan endpointlar, tavsifli modellar, misollar va javob hujjatlari. Bu — professional, o'zini hujjatlovchi API.

python
"""to'liq hujjatlangan API: metama'lumot, teglar, model tavsiflari, misollar, javob hujjatlari; o'zini hujjatlovchi."""

import warnings
warnings.filterwarnings("ignore")

from typing import Annotated

from fastapi import FastAPI, HTTPException, Query
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI(
    title="Wisar Kurslar API",
    description="Onlayn ta'lim platformasi uchun kurslar API si",
    version="1.0.0",
)


class KursKirish(BaseModel):
    nom: str = Field(description="Kurs nomi", examples=["Python asoslari"], min_length=2)
    narx: float = Field(ge=0, description="Kurs narxi (so'mda)", examples=[150000.0])


class KursJavob(BaseModel):
    id: int = Field(description="Kurs identifikatori")
    nom: str = Field(description="Kurs nomi")
    narx: float = Field(description="Kurs narxi")


BAZA: dict[int, dict] = {}
KEYINGI = 1


@app.get("/kurslar", response_model=list[KursJavob], summary="Kurslar ro'yxati", tags=["kurslar"])
def kurslar(q: Annotated[str | None, Query(description="Nom bo'yicha qidiruv")] = None):
    natija = list(BAZA.values())
    if q:
        natija = [k for k in natija if q.lower() in k["nom"].lower()]
    return natija


@app.post(
    "/kurslar",
    response_model=KursJavob,
    status_code=201,
    summary="Yangi kurs yaratish",
    tags=["kurslar"],
    responses={201: {"description": "Kurs yaratildi"}, 422: {"description": "Ma'lumot noto'g'ri"}},
)
def yarat(kurs: KursKirish):
    global KEYINGI
    yozuv = {"id": KEYINGI, "nom": kurs.nom, "narx": kurs.narx}
    BAZA[KEYINGI] = yozuv
    KEYINGI += 1
    return yozuv


@app.get(
    "/kurslar/{kurs_id}",
    response_model=KursJavob,
    summary="Bitta kurs",
    tags=["kurslar"],
    responses={404: {"description": "Kurs topilmadi"}},
)
def kurs(kurs_id: int):
    if kurs_id not in BAZA:
        raise HTTPException(status_code=404, detail="topilmadi")
    return BAZA[kurs_id]


client = TestClient(app)


def main() -> None:
    schema = client.get("/openapi.json").json()

    print("=== 1. API metama'lumoti ===")
    print(f"  {schema['info']['title']} v{schema['info']['version']}")

    print("\n=== 2. Hujjatlangan endpointlar ===")
    for yol, metodlar in sorted(schema["paths"].items()):
        for metod, info in metodlar.items():
            print(f"  {metod.upper()} {yol} — {info['summary']}")

    print("\n=== 3. Modellar (sxemalar) ===")
    print(f"  {sorted(schema['components']['schemas'].keys())}")

    print("\n=== 4. API haqiqatan ishlaydi ===")
    client.post("/kurslar", json={"nom": "Python", "narx": 100})
    client.post("/kurslar", json={"nom": "Go", "narx": 120})
    print(f"  yaratilgan kurslar: {len(client.get('/kurslar').json())}")
    print(f"  qidiruv (?q=py): {[k['nom'] for k in client.get('/kurslar?q=py').json()]}")
    print("  ⭐ to'liq hujjatlangan, o'zini tavsiflovchi API")


if __name__ == "__main__":
    main()

Natijaning muhim qismi:

text
=== 1. API metama'lumoti ===
  Wisar Kurslar API v1.0.0

=== 2. Hujjatlangan endpointlar ===
  GET /kurslar — Kurslar ro'yxati
  POST /kurslar — Yangi kurs yaratish
  GET /kurslar/{kurs_id} — Bitta kurs

=== 3. Modellar (sxemalar) ===
  ['HTTPValidationError', 'KursJavob', 'KursKirish', 'ValidationError']

=== 4. API haqiqatan ishlaydi ===
  yaratilgan kurslar: 2
  qidiruv (?q=py): ['Python']
  ⭐ to'liq hujjatlangan, o'zini tavsiflovchi API

Nima ko'rsatdi: 2.1–2.8-bo'limlar.

5. To'g'ri va noto'g'ri tushunishlar

Noto'g'ri fikr To'g'risi
"Hujjatni qo'lda yozish" FastAPI avtomatik
"Hujjat eskiradi" Koddan — har doim mos
"/docs sozlash kerak" Avtomatik mavjud
"OpenAPI — FastAPI'niki" Standart (til-mustaqil)
"Tavsif keraksiz" Mijoz uchun muhim
"Teg — bezak" Guruhlash (tashkil)
"Model tavsifsiz" Field(description) foydali
"Hujjat alohida ish" Kod o'zi hujjat

6. Keng tarqalgan xatolar va yechimlari

1. Metama'lumotni bermaslik

python
app = FastAPI()                             # ⚠️ nomsiz, versiyasiz
app = FastAPI(title="...", version="1.0.0") # ✅

2. Teglar bilan guruhlamaslik

python
@app.get("/kurslar")                        # ⚠️ guruhsiz
@app.get("/kurslar", tags=["kurslar"])      # ✅

3. Model tavsifsiz

python
nom: str                                    # ⚠️ tavsifsiz
nom: str = Field(description="Kurs nomi")   # ✅

4. summary bermaslik

python
@app.get("/kurslar")                        # docstring yoki
@app.get("/kurslar", summary="Ro'yxat")     # ✅ aniq

5. Javob shaklini hujjatlamaslik

python
@app.get("/kurslar/{id}")                   # ⚠️ javob noaniq
@app.get("/kurslar/{id}", response_model=KursJavob)   # ✅

6. Xato javoblarni hujjatlamaslik

python
# faqat 200 hujjatda                        # ⚠️ 404-chi?
responses={404: {"description": "..."}}      # ✅

7. Hujjatni kod'dan ajratish

python
# alohida Word/wiki hujjat                  # ⚠️ eskiradi
# ✅ kod o'zi hujjat (FastAPI)

7. Integratsiya — bu bilim qayerda kerak bo'ladi

  • 20.5-dars (o'tilgan): Pydantic — model sxemasi, "yagona manba"
  • 19.7-dars (o'tilgan): hujjatlash — docstring, MkDocs
  • 20.2-dars (o'tilgan): REST — API dizayni, hujjat
  • 19.5-dars (o'tilgan): versiyalash — version
  • 23-qism: baza — to'liq ilova hujjati

8. Eng yaxshi amaliyotlar

  1. Ilova metama'lumotini bering (title, description, version).

  2. Endpointlarni tags bilan guruhlang.

  3. summary/description bilan endpointni tavsiflang.

  4. Model maydonlarini Field(description) bilan hujjatlang.

  5. examples bilan namuna bering.

  6. response_model va responses bilan javobni hujjatlang.

  7. Hujjatni kod'dan yarating (alohida saqlamang).

  8. /docsda API'ni sinab ko'ring (mijoz nuqtayi nazaridan).

9. Amaliy topshiriq

Vazifa 1: Bashorat qiling

python
1.  # /docs nima?
2.  # /redoc nima?
3.  # OpenAPI nima?
4.  # hujjat qayerdan yaratiladi?
5.  # title/version qayerda?
6.  # tags nima uchun?
7.  # Field(description) nima?
8.  # examples nima?
9.  # response_model hujjatda nima beradi?
10. # responses nima?
11. # hujjat eskiradimi?
12. # /openapi.json nima?
Javoblar
  1. Swagger UI (interaktiv hujjat, sinab ko'rish)
  2. ReDoc (o'qiladigan hujjat)
  3. API'ni tavsiflovchi standart (JSON)
  4. Kod'dan (tip belgilari, modellar) — avtomatik
  5. Ilova metama'lumotida (FastAPI(...))
  6. Endpointlarni guruhlash
  7. Maydon tavsifi (hujjatda)
  8. So'rov/javob namunasi
  9. Javob shakli (sxema)
  10. Turli status kodlar hujjati
  11. Yo'q (kod'dan — har doim mos)
  12. OpenAPI sxema (JSON)

Vazifa 2: Xatolarni tuzating

python
1.  app = FastAPI()                     # metama'lumot

2.  @app.get("/kurslar")                # teg

3.  nom: str                            # tavsif

4.  @app.get("/kurslar/{id}")           # javob shakli

5.  # faqat 200 hujjatda                # xato javob
Javoblar
python
1.  app = FastAPI(title="...", version="1.0.0")

2.  @app.get("/kurslar", tags=["kurslar"])

3.  nom: str = Field(description="Kurs nomi")

4.  @app.get("/kurslar/{id}", response_model=KursJavob)

5.  responses={404: {"description": "topilmadi"}}

Vazifa 3: Hujjatlangan API

To'liq hujjatlangan kurs API:

  1. Metama'lumot (title, description, version)
  2. Teglar bilan guruhlangan endpointlar
  3. Tavsifli modellar (Field)
  4. /openapi.json ni tekshiring

Vazifa 4: Misollar bilan boyitish

Modellar uchun misollar:

  1. Har maydonga examples
  2. So'rov va javob namunalari
  3. /docsda "Try it out" bilan sinash
  4. Sxemada misollarni tekshiring

Vazifa 5: Javob hujjatlari

To'liq javob hujjati:

  1. response_model (muvaffaqiyat)
  2. responses (404, 422, 403)
  3. Har status kod tavsifi
  4. Sxemada tekshiring

Vazifa 6: OpenAPI tahlili

/openapi.json ni tahlil qiling:

  1. Barcha endpointlarni chiqarish
  2. Har birining metod, summary, tags
  3. Barcha modellar (sxemalar)
  4. Hujjat to'liqligini tekshiruvchi skript

Vazifa 7: O'ylash

FastAPI hujjati koddan avtomatik yaratiladi — bu 20.5 dagi "yagona haqiqat manbai" tamoyilining yakuni: bir kod validatsiya, seriyalizatsiya va hujjatni beradi. An'anaviy yondashuvda hujjat alohida yozilar va eskirar edi. Kod va hujjat "sinxron" bo'lishining afzalligi nima, va "bajaruvchi hujjat" (kod o'zi hujjat) tushunchasi dasturlashning boshqa qaysi joylarida uchraydi?

Javob

Qisqa javob: FastAPI'da hujjat koddan yaratiladi, shuning uchun ular hech qachon farqlanmaydi — kod o'zgarsa, hujjat avtomatik yangilanadi. An'anaviy alohida hujjat (Word, wiki) kod bilan sinxrondan chiqadi (eskiradi). "Kod o'zi hujjat" (bajaruvchi hujjat) afzalligi: hujjat har doim to'g'ri, alohida ish yo'q, va u sinab ko'rilgan (kod ishlaydi — hujjat to'g'ri). Bu tushuncha keng: tip belgilari (kod o'zini hujjatlaydi), test (ishlashni hujjatlaydi), docstring, "kod o'zini tushuntirsin" tamoyili.

1. Sinxron hujjat afzalligi

Alohida hujjat Kod'dan hujjat
Eskiradi Har doim mos
Qo'lda yangilash Avtomatik
Sinovsiz Kod ishlaydi = to'g'ri
Ikki manba Yagona manba

2. "Bajaruvchi hujjat"

Hujjat — bajariladigan kod'ning bir qismi (tip, model, tavsif). U ishlaydi, shuning uchun to'g'ri. Alohida yozilgan hujjat — faqat matn, tekshirilmaydi.

3. Yagona manba tamoyili (20.5)

Bir kod → validatsiya + seriyalizatsiya + hujjat. Bu takrorni yo'qotadi va farqlanishni oldini oladi.

4. "Kod o'zini hujjatlaydi" boshqa joyda

Element Qanday hujjatlaydi
Tip belgisi Parametr/qaytarish turi
Test Kutilgan xatti-harakat
Docstring Funksiya maqsadi
Aniq nom Niyat
OpenAPI API shartnomasi

5. Muhandislik saboqlari

  1. Hujjat kod bilan sinxron bo'lsin (eskirmasin)
  2. "Bajaruvchi hujjat" — ishlaydi, to'g'ri
  3. Yagona manba — bir kod, ko'p natija
  4. Kod o'zini hujjatlasin (tip, test, nom)

6. Xulosa

  1. FastAPI hujjati kod'dan (avtomatik, sinxron)
  2. Alohida hujjat eskiradi; kod'dan — har doim to'g'ri
  3. "Bajaruvchi hujjat" — ishlaydigan, ishonchli
  4. Yagona manba — 20-qismning markaziy tamoyili

Nimani mustahkamlaydi: 2.1–2.8-bo'limlar.

Xulosa

Bu darsda hujjatlar va OpenAPI'ni o'rgandik va 20-qismni yakunladik.

Eng muhim uch fikr:

  1. Avtomatik interaktiv hujjatlar. FastAPI hech qanday qo'shimcha ishsiz hujjat yaratadi: /docs (Swagger UI — interaktiv, endpointlarni sinab ko'rish mumkin), /redoc (ReDoc — o'qiladigan) va /openapi.json (OpenAPI sxema). Hujjat koddan (tip belgilari, Pydantic modellari, tavsiflar) olinadi — shuning uchun har doim kodga mos, hech qachon eskirmaydi.

  2. Hujjatni boyitish. Ilova metama'lumoti (title, description, version), endpoint tavsiflari (summary, description, tags — guruhlash), model maydon tavsiflari (Field(description, examples)) va javob hujjatlari (response_model, responses) — hammasi /docsda ko'rinadi. Bu API'ni o'zini tavsiflovchi qiladi: mijoz dasturchi endpointni tushunadi va sinab ko'radi.

  3. Yagona manba yakuni. FastAPI hujjati koddan avtomatik yaratiladi — bu 20.5 dagi "yagona haqiqat manbai" tamoyilining yakuni: bir kod validatsiya, seriyalizatsiya va hujjatni beradi. "Bajaruvchi hujjat" (kod o'zi hujjat) — an'anaviy alohida hujjatdan ustun: u ishlaydi, shuning uchun to'g'ri, va kod bilan hech qachon farqlanmaydi.

20-qism yakuni

Web-backend (FastAPI) qismida zamonaviy, professional API qurishning to'liq yo'lini o'rgandik — HTTP asoslaridan avtomatik hujjatlargacha.

Dars Mavzu Asosiy g'oya
20.1 Web qanday ishlaydi: HTTP So'rov/javob, metodlar, status kodlar
20.2 REST tamoyillari Resurs, metod ↔ amal, holatsizlik
20.3 FastAPI kirish Ilova, endpoint, avtomatik hujjat
20.4 Route va parametrlar Yo'l/so'rov parametri, validatsiya
20.5 Pydantic modellari So'rov tanasi, validatsiya, yagona manba
20.6 So'rov va javob Status kod, sarlavha, cookie, javob turi
20.7 Bog'liqliklar (DI) Depends, takrorni yo'qotish, IoC
20.8 Baza bilan ulash yield bog'liqlik, parametrlangan SQL
20.9 CRUD Create/Read/Update/Delete naqshi
20.10 Autentifikatsiya: JWT Parol hash, token, holatsiz auth
20.11 Ruxsatlar Rol, egalik, 401 vs 403
20.12 Xatolarni boshqarish HTTPException, handler, izchil shakl
20.13 Fayl yuklash UploadFile, tekshiruv, xavfsizlik
20.14 Fon vazifalari BackgroundTasks, muhim yo'l
20.15 Testlash TestClient, dependency_overrides
20.16 Hujjatlar va OpenAPI /docs, /openapi.json, yagona manba

Umumiy tamoyillar:

  1. Tip'ga tayanish: tip belgilari validatsiya, seriyalizatsiya va hujjatni beradi.
  2. Yagona haqiqat manbai: kod — validatsiya + hujjat + sxema (takror yo'q).
  3. Dependency Injection: bog'liqlik e'lon qilinadi (yaratilmaydi) — sinaluvchan, ajratilgan.
  4. Xavfsizlik qatlamlari: autentifikatsiya, ruxsat, validatsiya, "mijozga ishonma".

Keyingi qism — 21-qism: Django — boshqa falsafadagi to'liq freymvork: "batareyalar ichida" (admin, ORM, autentifikatsiya tayyor), MVT arxitekturasi va Django REST Framework bilan API qurish.

Ulashish:Telegram'da

Izohlar (0)

Izoh yozish uchun kiring.

  • Hozircha izoh yo'q. Birinchi bo'ling!
20.16-dars: Hujjatlar va OpenAPI — IlmHamroh