/docs дээр POST турших

Танилцуулга

Энэ хичээл богино бөгөөд гардан дадлагын шинжтэй. Бид шинэ ойлголт сурахгүй; оронд нь аль хэдийн байгаа хэрэгсэл — /docs хуудас — дээрээ жинхэнэ мастер болно.

Бүлэг 1-д би /docs-ыг таны лаборатори гэж нэрлэсэн. Түвшин 1-д бид түүнийг голдуу GET туршихад ашигласан — Try it out, Execute, хариу харах. Гэхдээ POST-той хамт /docs илүү хүчирхэг болно: та JSON body-г шууд засварлаж, зөв ба буруу өгөгдөл илгээж, хоёр үр дүнг харьцуулж чадна. Postman, Insomnia, curl гэх мэт тусдаа хэрэгсэл огт хэрэггүй.

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

Бэлтгэл

main.py файлаа дараах кодоор солино. Энэ бол өмнөх хичээлийн кодтой төстэй, гэхдээ жижиг цэвэрхэн хувилбар:

python

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

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

notes = []
next_id = 1


class Note(BaseModel):
    text: str
    priority: str = "энгийн"
    done: bool = False


@app.get("/notes")
def get_notes():
    return notes


@app.get("/notes/{note_id}")
def get_note(note_id: int):
    for note in notes:
        if note["id"] == note_id:
            return note
    raise HTTPException(status_code=404, detail="Тэмдэглэл олдсонгүй")


@app.post("/notes", status_code=201)
def create_note(note: Note):
    global next_id
    new_note = note.model_dump()
    new_note["id"] = next_id
    notes.append(new_note)
    next_id += 1
    return new_note

Хадгална. Сервер ажиллаж байгаа эсэхийг шалгаад /docs хуудсаа нээнэ:

http://127.0.0.1:8000/docs

/docs хуудасны бүтэц — POST талаас

/docs дээр гурван endpoint харагдана. POST /notes мөрийг анзаараарай — түүний өнгө GET-үүдээс өөр (ихэвчлэн ногоон GET, шар/улбар шар POST). Swagger UI method бүрийг өнгөөр ялгадаг тул хуудсыг хараад л аль нь унших, аль нь бичих endpoint болохыг мэднэ.

POST /notes дээр товшино. Мөр задарч, дотор нь хэд хэдэн хэсэг гарна.

Request body — энэ бол POST-ын гол хэсэг, GET-д байдаггүй. Хэрэглэгч ямар өгөгдөл илгээхийг харуулна.

Parameters — энэ endpoint-д path/query parameter байвал энд гарна. Одоохондоо байхгүй тул хоосон эсвэл огт харагдахгүй.

Responses — ямар хариу гарч болзошгүйг харуулна: 201 (амжилт), 422 (validation алдаа).

Request body-г ойлгох: Example vs Schema

Request body хэсэгт хоёр таб байдаг: Example Value болон Schema. Хоёуланг нь харцгаая.

Example Value

Анхдагчаар Example Value харагдана — FastAPI таны model-оос үүсгэсэн жишээ JSON:

json

{
  "text": "string",
  "priority": "энгийн",
  "done": false
}

Талбар бүрийн төрлийг харуулж байна. text нь текст тул "string". priority нь default утгатай тул "энгийн". done нь bool, default нь false.

Энэ жишээ бол таны бөглөх маягтын загвар юм. Try it out дарахад яг энэ текст засварлах талбарт орж ирнэ.

Schema

Schema таб дээр товшвол илүү техникийн харагдац гарна:

Note {
  text*        string
  priority     string    default: энгийн
  done         boolean   default: false
}

Энд од (*) нь заавал талбарыг заана. text дээр од — заавал. priority болон done дээр од байхгүй — заавал бус (default-тай). Бүлэг 4-т сурсан заавал/заавал бусын ялгаа энд харагдаж байна.

Schema нь Example-ээс илүү нарийвчлалтай: төрөл, заавал эсэх, default утга бүгд тодорхой. Аль ч табыг ашиглаж болно; засварлахад Example илүү тохиромжтой, ойлгоход Schema илүү тодорхой.

Зөв body илгээх

Одоо гардан ажиллая. Try it out дарна. Example JSON нь засварлах боломжтой талбар болж хувирна.

Текстийг бүхэлд нь дараахаар солино:

json

{
  "text": "Номын сангаас ном авах",
  "priority": "чухал"
}

done талбарыг зориудаар орхилоо — default (false) хэрэгжихийг харах гэж.

Execute дарна. Доор хэд хэдэн хэсэг гарч ирнэ.

Curl

Эхлээд Curl хэсэг — таны хийсэн хүсэлтийг терминалын тушаал хэлбэрээр:

curl -X 'POST' \
  'http://127.0.0.1:8000/notes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Номын сангаас ном авах",
  "priority": "чухал"
}'

Энэ нь GET-ийн curl-аас илүү нарийн. -X 'POST' — method. -H 'Content-Type: application/json' — "би JSON илгээж байна" гэсэн толгой (header). -d '...' — илгээж буй body. Одоо гүнзгий ойлгох шаардлагагүй, гэхдээ POST хүсэлт GET-ээс илүү бүрэлдэхүүнтэй гэдгийг харж болно.

Request URL

http://127.0.0.1:8000/notes

Зөвхөн хаяг — body энд харагдахгүй, учир нь POST-ийн өгөгдөл body-д нуугдана (Бүлэг 5-ын Хичээл 1-ээс танил).

Server response

Хамгийн чухал хэсэг. Code нь 201, Response body:

json

{
  "text": "Номын сангаас ном авах",
  "priority": "чухал",
  "done": false,
  "id": 1
}

Гурван зүйлийг анзаараарай. done нь false — та илгээгээгүй, default хэрэгжсэн. id нь 1 — сервер нэмсэн. Status 201 — үүсгэсэн.

Буруу body илгээх

Одоо зориудаар алдаа гаргая. Try it out талбарт:

json

{
  "priority": "чухал"
}

text талбарыг орхилоо — гэтэл text заавал (default байхгүй).

Execute дарна.

Server response (статус 422):

json

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "text"],
      "msg": "Field required",
      "input": {"priority": "чухал"}
    }
  ]
}

Танил бүтэц. text дутуу тул missing. loc нь ["body", "text"]. Code нь 422.

Хоёр Execute-ийн ялгааг ажиглаарай. Эхнийх 201 өгсөн, тэмдэглэл үүссэн. Хоёр дахь нь 422 өгсөн, юу ч үүсээгүй. Таны функц хоёр дахь удаад огт дуудагдаагүй — Pydantic хаалган дээр зогсоосон.

Хоёр үр дүнг зэрэгцүүлж унших дадлага

Одоо системтэй туршъя. Дараах хэдэн body-г ээлж дараалан илгээж, гарах Code болон Response-ыг ажиглаарай. Энэ бол таны API-ийн зан төлөвийг бүрэн ойлгох дадлага.

Туршилт 1: зөвхөн заавал талбар

json

{"text": "Тест 1"}

Code: 201. priority нь "энгийн", done нь false (default-ууд).

Туршилт 2: буруу төрөл

json

{"text": "Тест 2", "done": "магадгүй"}

Code: 422. done нь bool байх ёстой, "магадгүй" хувирахгүй. type нь bool_parsing.

Туршилт 3: bool хувиргалт

json

{"text": "Тест 3", "done": "true"}

Code: 201. "true" гэсэн текст true болж хувирсан (Бүлэг 2-оос танил bool хувиргалт). Response-д done: true.

Туршилт 4: илүү талбар

json

{"text": "Тест 4", "color": "улаан"}

Code: 422. color бол model-д байхгүй талбар. Pydantic default байдлаар илүү талбарыг татгалздаг (Бүлэг 4-ийн үсгийн алдааны хэсгээс). type нь extra_forbidden.

Туршилт 5: JSON синтакс алдаа

json

{"text": "Тест 5" "priority": "чухал"}

(Хоёр талбарын хооронд таслал дутуу.)

Swagger UI ихэвчлэн үүнийг илгээхээс өмнө улаанаар анхааруулна — засварлах талбарын доор "Bad JSON" гэх мэт мессеж гарна. Хэрэв та түүнийг тойрч илгээвэл 422 ирж, type нь json_invalid болно. Энэ нь талбарын шалгалтаас өмнө болдог: эхлээд "энэ хүчинтэй JSON мөн үү?", дараа нь "талбарууд зөв үү?".

Таван туршилтыг хийсэн бол та Code-ийн хоёр бүлгийг тодорхой мэдэрсэн байх ёстой: 2xx (амжилт) болон 4xx (хэрэглэгчийн алдаа).

GET-ийг мөн турших

/docs дээр GET endpoint-үүдийг ч туршиж болно. GET /notes/{note_id} дээр товшоод Try it out дарна. Одоо Parameters хэсэгт note_id талбар гарна (body биш, path parameter).

note_id талбарт 1 бичээд Execute:

Code: 200, эхэнд үүсгэсэн тэмдэглэл.

Дараа нь 99 бичээд Execute:

Code: 404, {"detail":"Тэмдэглэл олдсонгүй"}.

Path parameter-ийн туршилт body-гүй, зөвхөн нэг талбар — POST-ынхаас энгийн. Гэхдээ ижил /docs хэрэгсэл хоёуланг зохицуулж байна.

Бусад хэрэгслүүд (танилцуулга)

/docs бол хамгийн хялбар туршилтын хэрэгсэл, гэхдээ цорын ганц биш. Мэдэж байх нь зүйтэй хэдэн зүйл:

curl — терминалаас HTTP хүсэлт илгээдэг хэрэгсэл. /docs бүр хүсэлтийнхээ curl тушаалыг харуулдаг тул та түүнийг хуулж, терминал дээр ажиллуулж болно.

Postman / Insomnia — HTTP хүсэлт зохион байгуулах график программууд. Том төсөлд ашигтай, гэхдээ суулгах шаардлагатай.

requests — Курс 2-т сурсан Python сан. Кодоор туршихад тохиромжтой.

Энэ сургалтад бид зөвхөн /docs-ыг ашиглана, учир нь тэр аль хэдийн бэлэн, суулгах шаардлагагүй, таны кодтой үргэлж синхрон байдаг (шинэ endpoint нэмэхэд шууд гарч ирнэ). Гэхдээ ажлын байранд эдгээр бусад хэрэгслүүдтэй тааралдвал тэдгээр нь ижил зорилготой гэдгийг мэдэж байгаарай.

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

Try it out дараагүй

Хэрэв та Execute дарж чадахгүй, эсвэл JSON засварлаж чадахгүй байвал — эхлээд Try it out товч дарах ёстой. Тэр товч хуудсыг "унших горим"-оос "туршилтын горим" руу шилжүүлдэг.

Хуучин хариу харах

Execute дарсны дараа хуудсаа скролл хийж доош харна уу. Заримдаа шинэ хариу доор гарч ирдэг тул дээд талд хуучин мэдээлэл харагдаж, төөрөгдүүлдэг. Хамгийн сүүлийн Server response хэсгийг хараарай.

Сервер зогссон

Хэрэв Execute дарахад удаан хугацаанд хариу ирэхгүй, эсвэл "Failed to fetch" гэх мэт алдаа гарвал — таны сервер зогссон байх магадлалтай. Терминалаа шалгаарай. Хэрэв зогссон бол fastapi dev main.py-аар дахин асаа. (venv) идэвхтэй эсэхийг шалгах — Хэрэв ModuleNotFoundError гарвал — venv идэвхтэй эсэхээ шалгаарай.

/docs хуудас хуучин

Хэрэв та кодоо өөрчилсөн атлаа /docs дээр өөрчлөлт харагдахгүй бол хуудсаа хатуу шинэчил (Ctrl+Shift+R). Өөрчлөлт харагдахгүй бол — терминал дээр reload болсныг шалгаарай.

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

Хүсвэл Note model-д шинэ талбар нэмээд (жишээ нь tags: str = ""), /docs хуудсаа шинэчилээд, Request body хэсэгт шинэ талбар гарч ирснийг ажиглаарай. Кодоо өөрчлөхөд баримт бичиг шууд шинэчлэгддэгийг гар дээрээ мэдрэх нь FastAPI-ийн гол давуу талыг бататгана.

Сонирхвол Execute дарсны дараа гарч ирдэг Curl тушаалыг хуулж, шинэ терминал дээр (venv идэвхтэй) ажиллуулж үзээрэй. Яг ижил хариу ирнэ. Энэ нь /docs товч болон terminal тушаал хоёр ижил зүйл хийдгийг харуулна.

Товч дүгнэлт

• /docs бол POST туршихад бүрэн хэрэгсэл — Postman гэх мэт тусдаа программ хэрэггүй.

• POST endpoint дээр Request body хэсэг гарна; Example (засварлахад) болон Schema (ойлгоход) гэсэн хоёр таб.

• Try it out -> body засах -> Execute -> Code болон Response body унших.

• Зөв body -> 201; заавал талбар дутуу -> 422; илүү талбар -> 422 (extra_forbidden); буруу JSON -> 422 (json_invalid).

• Swagger UI method бүрийг өнгөөр ялгадаг; JSON синтакс алдааг ихэвчлэн урьдчилан анхааруулдаг.

• GET-ийг ч ижил хэрэгслээр турших боломжтой (Parameters хэсэгт path/query талбар гарна).

• curl, Postman, requests бол ижил зорилготой бусад хэрэгслүүд.

Одоо та POST-ыг бичиж, туршиж бүрэн эзэмшлээ. CRUD-ийн эхний хоёр үсэг — Create (POST) болон Read (GET) — таны гарт байна. Дараагийн хичээлд бид үлдсэн хоёрыг нэмнэ: PUT (засах) болон DELETE (устгах). Тэдгээрийг сурснаар та бүрэн CRUD-тай болно — өгөгдлийг үүсгэх, унших, засах, устгах бүх чадвар. Тэр нь Түвшин 2-ын гол бүтээн байгуулалт болох Тэмдэглэлийн API v1 руу хийх сүүлчийн алхам юм.