Tags — /docs хуудсаа цэгцлэх

Танилцуулга

Энэ хичээл богино. Өмнөх хичээлд бид tags параметрийг товч дурдаад өнгөрсөн — тэр нь /docs хуудсан дээр endpoint-уудыг бүлэглэж байсан. Одоо түүнд бүрэн зориулъя.

tags бол зөвхөн гоо сайхны зүйл биш. Олон endpoint-той API-д /docs хуудас урт, замбараагүй болдог. Tags нь түүнийг ойлголтоор бүлэглэж, унших, ашиглахад хялбар болгодог. Мэргэжлийн API бүр tag ашигладаг тул энэ жижиг хэрэгслийг зөв эзэмших нь зүйтэй.

Асуудлыг харах

Tag-гүй API-г төсөөлье. Арван endpoint байвал /docs хуудас ийм харагдана:

GET    /notes
POST   /notes
GET    /notes/{note_id}
PUT    /notes/{note_id}
DELETE /notes/{note_id}
GET    /users
POST   /users
GET    /users/{user_id}
PUT    /users/{user_id}
DELETE /users/{user_id}

Арван мөр, нэг урт жагсаалт. Тэмдэглэлийн endpoint хаана дуусаж, хэрэглэгчийнх хаанаас эхэлж байгаа нь тодорхойгүй. Тодорхой нэг endpoint олохын тулд бүх жагсаалтыг хайх ёстой.

Хорин, гуч, тавин endpoint болбол энэ нь бүр ч дор болно. Хэрэглэгч (эсвэл өөрөө та хэдэн сарын дараа) юу хаана байгааг олж ядна.

Зүйрлэл: цэсний хэсгүүд (дахин)

Өмнөх хичээлд APIRouter-ыг цэсний бүлэг хуудас гэж зүйрлэсэн. Tags бол тэр хуудсуудын гарчиг юм.

Том цэсэнд хоол зүгээр л дараалан жагсдаггүй. "Зууш", "Үндсэн хоол", "Ундаа", "Амттан" гэсэн гарчигтай хэсэгт хуваагддаг. Зочин "амттан хүсэж байна" гэвэл шууд амттангийн хэсэг рүү очно, бүх цэсийг уншихгүй.

tags бол яг тэр гарчиг юм. "Тэмдэглэл", "Хэрэглэгч" гэсэн бүлэг үүсгэж, зочин (API ашиглагч) хайж байгаа хэсэг рүүгээ шууд очдог болгоно.

Tag хэрхэн нэмэх вэ

Tag нэмэх хоёр арга бий. Аль хэдийн өмнөх хичээлд эхнийхийг харсан.

Арга 1: router дээр (бүх endpoint-д)

Router үүсгэхдээ tags зарлавал тэр router-ийн бүх endpoint нэг tag авна:

python

router = APIRouter(prefix="/notes", tags=["Тэмдэглэл"])

Энэ бол хамгийн түгээмэл, хамгийн цэвэрхэн арга. Нэг router = нэг нөөц = нэг tag. Notes router-ийн бүх endpoint "Тэмдэглэл" бүлэгт орно.

tags нь жагсаалт гэдгийг анзаараарай (["Тэмдэглэл"]) — учир нь нэг endpoint олон tag-тай байж болно (ховор, гэхдээ боломжтой). Ихэвчлэн ганц tag хангалттай.

Арга 2: тодорхой endpoint дээр

Ганц endpoint-д tag нэмэхийг хүсвэл decorator дээр зарлана:

python

@router.get("/special", tags=["Онцгой"])
def special_endpoint():
    ...

Энэ endpoint нь router-ийн tag-аас гадна "Онцгой" tag ч авна. Практикт энэ ховор хэрэгтэй; ихэнх тохиолдолд router дээрх tag хангалттай.

Бүрэн жишээ

Өмнөх хичээлийн бүтцийг ашиглая. app/routers/notes.py-д tag аль хэдийн байгаа:

python

# app/routers/notes.py (эхний хэсэг)
router = APIRouter(prefix="/notes", tags=["Тэмдэглэл"])

app/routers/users.py-д ч:

python

# app/routers/users.py (эхний хэсэг)
router = APIRouter(prefix="/users", tags=["Хэрэглэгч"])

Хоёр router, хоёр tag. Одоо /docs хуудсыг харъя.

Туршина

Сервер ажиллаж байгаа эсэхийг шалгаад:

http://127.0.0.1:8000/docs

Endpoint-ууд одоо бүлэглэгдсэн харагдана:

Тэмдэглэл
  GET   /notes
  POST  /notes
  GET   /notes/{note_id}

Хэрэглэгч
  GET   /users
  POST  /users

Тэмдэглэл болон Хэрэглэгч гэсэн хоёр гарчигтай бүлэг. Тус бүр нээж, хааж болно — гарчиг дээр товшвол доtorх endpoint-ууд эвхэгдэнэ. Олон бүлэгтэй API-д хэрэгтэй хэсгээ нээж, бусдыг хааж, анхаарлаа төвлөрүүлж болно.

Кодын бүтэц (хоёр router файл) баримт бичгийн бүтэц (хоёр бүлэг) болж шууд тусгагдсан. Энэ бол цэвэрхэн зохион байгуулалтын шинж: код хэрхэн бүлэглэгдсэн бол баримт бичиг ч тэр хэвээр харагдана.

Tag-д тайлбар нэмэх

Tag нь зөвхөн нэр биш, тайлбартай ч байж болно. Энэ нь /docs дээр бүлэг бүрийн дор тайлбар харуулна.

Тайлбарыг main.py-д, app үүсгэхэд зарлана:

python

# main.py
from fastapi import FastAPI

from app.routers import notes, users

tags_metadata = [
    {
        "name": "Тэмдэглэл",
        "description": "Тэмдэглэл үүсгэх, унших, засах, устгах үйлдлүүд.",
    },
    {
        "name": "Хэрэглэгч",
        "description": "Хэрэглэгчийн бүртгэл, мэдээлэл.",
    },
]

app = FastAPI(
    title="Тэмдэглэлийн API",
    openapi_tags=tags_metadata,
)

app.include_router(notes.router)
app.include_router(users.router)

Хадгална.

Кодын задаргаа

tags_metadata — жагсаалт, элемент бүр нэг tag-ийн мэдээлэл. name нь tag-ийн нэр (router дээрх нэртэй яг таарах ёстой), description нь тайлбар.

openapi_tags=tags_metadata — энэ жагсаалтыг app-д өгч байна.

name нь router дээрх tags=["Тэмдэглэл"] дэх нэртэй яг таарах нь чухал. Хэрэв "Тэмдэглэл" (router) болон "Тэмдэглэлүүд" (metadata) гэж бичвэл тэдгээр нь тусдаа хоёр бүлэг болно — нэг нь endpoint-той (router-ийнх), нөгөө нь тайлбартай (metadata-гийнх), гэхдээ хоосон.

Туршина

/docs хуудсаа дахин нээнэ:

Тэмдэглэл
Тэмдэглэл үүсгэх, унших, засах, устгах үйлдлүүд.
  GET   /notes
  ...

Хэрэглэгч
Хэрэглэгчийн бүртгэл, мэдээлэл.
  GET   /users
  ...

Одоо бүлэг бүрийн дор тайлбар харагдана. Хэрэглэгч (API ашиглагч) энэ бүлэг юуны тухай болохыг гарчиг уншаад ойлгоно.

Энэ нь том API-д ялангуяа ашигтай. Хорин бүлэгтэй API-д тайлбар нь хэрэглэгчийг зөв хэсэг рүү хурдан хөтөлдөг.

Tag-ийн дараалал

tags_metadata дахь дараалал нь /docs дээрх бүлгүүдийн дарааллыг тодорхойлно. Дээрх жишээнд "Тэмдэглэл" эхэлж, "Хэрэглэгч" дараа нь. Хэрэв та тэдгээрийг сольвол /docs дээр дараалал ч солигдоно.

Metadata-д зарлагдаагүй tag-ууд (жишээ нь та зарим router-т metadata бичээгүй бол) жагсаалтын төгсгөлд, endpoint эхэлж бүртгэгдсэн дарааллаар гарна.

Энэ нь чухал зохион байгуулалтын хэрэгсэл: хамгийн чухал, түгээмэл ашиглагддаг бүлгүүдийг дээр тавьж болно. Жишээ нь capstone-д "Ном", "Гишүүн", "Зээл" гэсэн дарааллаар зохион байгуулж, хэрэглэгч гол функцийг эхэнд харна.

Tag хэзээ хэрэгтэй вэ

Шударга байя: ганц нөөцтэй жижиг API-д tag заавал биш. Тэмдэглэлийн API v1-д (нэг нөөц) бид tag ашиглаагүй бөгөөд тэр зүгээр байсан.

Tag дараах үед хэрэгтэй болно:

• Хоёр ба түүнээс дээш нөөцтэй бол (тэмдэглэл, хэрэглэгч, ном) — тус бүрийг бүлэглэх.

• /docs хуудас урт болж, endpoint олоход хэцүү болсон бол.

Дүрэм энгийн: router бүрд tag өг. Нэг router = нэг нөөц = нэг tag. Энэ нь бараг үнэгүй (router дээр нэг параметр) бөгөөд /docs-ыг үргэлж цэгцтэй байлгадаг тул зуршил болгох нь зүйтэй.

Бид Тэмдэглэлийн API v2 болон capstone-д router бүрд tag өгнө.

Түгээмэл алдаанууд

Metadata болон router-ийн нэр таарахгүй

python

# router-т
router = APIRouter(tags=["Тэмдэглэл"])

# metadata-д
{"name": "Тэмдэглэлүүд", "description": "..."}   # өөр нэр!

Хоёр нэр таарахгүй тул /docs дээр хоёр бүлэг гарна: "Тэмдэглэл" (endpoint-той, тайлбаргүй) болон "Тэмдэглэлүүд" (тайлбартай, endpoint-гүй, хоосон). Засвар: хоёр нэрийг яг ижил болгох.

Tag-ийг string-ээр өгөх (жагсаалт биш)

python

router = APIRouter(tags="Тэмдэглэл")   # буруу — жагсаалт байх ёстой

tags нь жагсаалт байх ёстой. String өгвөл FastAPI түүнийг тэмдэгт бүрээр нь салгаж, хачирхалтай олон tag үүсгэж болно, эсвэл алдаа өгнө. Зөв: tags=["Тэмдэглэл"].

Кирилл tag ажиллах уу

Кирилл tag ("Тэмдэглэл", "Хэрэглэгч") бүрэн ажиллана — /docs дээр монголоор харагдана. Энэ нь UI-д харагдах текст тул монголоор байх нь зөв (JSON-ы түлхүүр латин байх ёстой гэсэн дүрмээс ялгаатай — tag бол түлхүүр биш, харагдах гарчиг). Хэрэглэгчид зориулсан баримт бичиг монголоор байх нь энэ курсын хэлний зарчимд тохирно.

Туршаад үзээрэй

Хүсвэл tags_metadata-д хоёр tag-ийн дарааллыг сольж (Хэрэглэгчийг эхэнд тавьж), /docs дээр бүлгийн дараалал өөрчлөгдсөнийг ажиглаарай. Дараа нь буцааж сольно.

Сонирхвол ганц endpoint-д router-ийн tag-аас өөр tag нэмж үзээрэй (Арга 2). Тэр endpoint хоёр бүлэгт зэрэг харагдахыг ажиглаарай — нэг endpoint олон бүлэгт орж болдгийг гар дээрээ хараарай.

Товч дүгнэлт

• Tags нь /docs хуудсан дээр endpoint-уудыг ойлголтоор бүлэглэнэ — урт жагсаалтыг цэгцтэй хэсэг болгоно.

• Хамгийн түгээмэл арга: router дээр APIRouter(tags=["Тэмдэглэл"]) — router-ийн бүх endpoint нэг tag авна.

• tags нь жагсаалт (["..."]), string биш.

• Tag-д тайлбар нэмэх: main.py-д openapi_tags=tags_metadata, name нь router-ийн tag-тай яг таарах ёстой.

• Metadata дахь дараалал нь /docs дээрх бүлгийн дарааллыг тодорхойлно.

• Кирилл tag ажиллана — tag бол харагдах гарчиг, JSON түлхүүр биш.

• Дүрэм: router бүрд tag өг (нэг router = нэг tag). Бараг үнэгүй, /docs-ыг цэгцтэй байлгана.

Бүлэг 7 дууслаа. Та одоо кодоо олон router болгон задалж, мэргэжлийн хавтасны бүтцэд зохион байгуулж, /docs хуудсаа tag-аар цэгцэлж чадна. Таны төсөл өсөхөд бэлэн боллоо.

Гэхдээ router-ууд өсөхөд шинэ асуудал гарч ирдэг: давтагдсан логик. Жишээ нь олон endpoint-д ижил хайлт/хязгаарлалтын параметр хэрэгтэй болно. Олон endpoint-д ижил шалгалт (жишээ нь API key) хэрэгтэй болно. Түвшин 4-т бүх endpoint-д ижил өгөгдлийн сангийн холболт хэрэгтэй болно. Энэ давтагдсан логикийг хуулах нь алдаатай, засахад бэрх.

Дараагийн бүлэг бүхэлдээ Depends — FastAPI-ийн хамаарлын систем — д зориулагдана. Энэ бол хуваалцсан логикийг нэг газар бичээд, олон endpoint руу автоматаар "тарих" механизм юм. Бид эхлээд ойлголтыг нь сурч, дараа нь дахин ашиглагдах шүүлтүүр үүсгэж, эцэст нь API key-ээр бичих үйлдлээ хамгаална. Depends бол FastAPI-ийн хамгийн хүчирхэг, хамгийн онцлог хэрэгслүүдийн нэг бөгөөд Түвшин 4-ийн өгөгдлийн сан түүн дээр бүрэн тулгуурлана.