/docs — автомат баримтжуулалтын аялал

Танилцуулга

Өмнөх хичээлийн төгсгөлд терминал дээр хоёр хаяг гарч ирснийг та санаж байгаа байх. Нэг нь таны сервер өөрөө, нөгөө нь ийм байсан:

Documentation at http://127.0.0.1:8000/docs

Энэ хоёр дахь хаяг бол FastAPI-ийн хамгийн гайхалтай, хамгийн ашигтай, гэхдээ шинэ суралцагчид хамгийн бага анхаардаг зүйл юм. Тиймээс бид түүнд бүтэн хичээл зориулж байна.

Энэ хичээлд шинэ код бичихгүй. Бид зөвхөн нэг хуудсыг нээж, түүн доторх бүх зүйлийг нэг нэгээр нь харна. Энэ хуудас нь сургалтын турш таны лаборатори болох тул түүнтэй сайн танилцах нь дараагийн зуун хичээлийг хөнгөвчилнө.

Баримт бичиг гэж юу вэ, яагаад асуудалтай байдаг вэ

API бол програмуудын хооронд ярианы хэл юм. Гэхдээ ярианы хэлийг ойлгохын тулд толь бичиг хэрэгтэй. API бүтээгч хүн "миний API руу ямар хаягаар ханддаг вэ, ямар өгөгдөл илгээх ёстой вэ, ямар хариу ирэх вэ" гэдгийг бичиж үлдээх ёстой. Энэ бичгийг documentation буюу баримтжуулалт гэдэг.

Асуудал нь энд байна. Уламжлалт байдлаар баримт бичгийг гараар бичдэг. Хөгжүүлэгч кодоо бичээд, дараа нь тусдаа баримт бичиг бичдэг. Тэгээд хэдэн долоо хоногийн дараа кодоо өөрчилдөг — гэхдээ баримт бичгээ шинэчлэхээ мартдаг. Хэдэн сарын дараа баримт бичиг худал ярьж эхэлдэг: "энэ хаяг ийм өгөгдөл буцаана" гэж бичсэн байхад бодит байдал дээр огт өөр зүйл буцаадаг. Дэлхийн бүх компанид энэ асуудал байдаг бөгөөд энэ нь маш их цаг, мэдрэл иддэг.

FastAPI үүнийг өөр аргаар шийдсэн: баримт бичгийг гараар бичдэггүй, кодоос нь автоматаар үүсгэдэг. Та шинэ endpoint нэмбэл баримт бичигт шууд гарч ирнэ. Та type hint өөрчилбөл баримт бичиг шууд өөрчлөгдөнө. Хоцрох боломжгүй, учир нь баримт бичиг бол код өөрөө.

Зүйрлэл: цэс өөрөө шинэчлэгддэг зоогийн газар

Курс 2-оос авчирсан зүйрлэлдээ буцаж очъё. API бол цэс — зочин юу захиалж болохыг тодорхойлдог. Ердийн зоогийн газарт цэсийг хэвлэдэг. Тогооч шинэ хоол нэмбэл цэсийг дахин хэвлэх ёстой, эс бөгөөс зочид тэр хоолны талаар хэзээ ч мэдэхгүй. Хоол хасвал бас дахин хэвлэх ёстой, эс бөгөөс зочид байхгүй хоол захиалж, зөөгч уучлалт гуйх болно.

FastAPI-ийн зоогийн газарт цэс нь гал тогооноос шууд уншиж, өөрөө бичигддэг. Тогооч шинэ хоол хийж чаддаг болмогц цэсэн дээр гарч ирнэ. Хоолны найрлагыг өөрчилвөл цэс дээрх тайлбар өөрчлөгдөнө. Цэс худал ярих боломжгүй, учир нь цэс бол гал тогооны толь юм.

Түүнээс ч илүү: энэ цэс дээр шууд захиалж болно. Та цэсэн дээрх хоол дээр товшоод "энийг авъя" гэж дарахад хоол ирдэг. Яг ийм зүйлийг /docs хуудас хийдэг — та түүн дээрээс endpoint-үүдээ шууд дуудаж, хариуг нь харж болно. Postman гэх мэт тусдаа программ суулгах шаардлагагүй.

Хуудсыг нээх

Терминал дээрээ серверээ асаана ((venv) идэвхтэй эсэхээ шалгаад):

fastapi dev main.py

Дараа нь browser дээрээ дараах хаягийг нээнэ:

http://127.0.0.1:8000/docs

Цагаан дэвсгэртэй, ногоон болон цэнхэр өнгийн хэсгүүдтэй хуудас нээгдэнэ. Энэ бол Swagger UI гэж нэрлэгддэг интерфейс — API-ийн дэлхийн стандарт хэрэгсэл. FastAPI түүнийг таны кодод суурилан бүтээж өгсөн.

(Энд screenshot тавих боломжтой: /docs хуудас анх нээгдсэн байдал.)

Хуудсын хэсгүүд

Дээд талын гарчиг

Хамгийн дээр том үсгээр FastAPI гэж бичсэн байх бөгөөд хажууд нь 0.1.0 гэсэн хувилбарын дугаар байна. Доор нь /openapi.json гэсэн жижиг холбоос харагдана.

Энэ гарчиг хаанаас ирсэн бэ? Таны кодоос. Та app = FastAPI() гэж бичихдээ ямар ч нэр өгөөгүй тул FastAPI өөрийн үндсэн нэрийг ашигласан. Хожим та түүнд өөрийн нэр өгч чадна — тэр үед энэ гарчиг өөрчлөгдөнө.

Endpoint-үүдийн жагсаалт

Гарчгийн доор таны бүх endpoint жагсаалт хэлбэрээр гарна. Одоохондоо танд ганц endpoint байгаа тул ганц мөр харагдана:

GET   /   Root

Гурван хэсгийг задалж харъя. GET бол HTTP method — Курс 2-ын Бүлэг 11-д та үүнтэй танилцсан, "өгөгдөл унш" гэсэн утгатай. Ногоон өнгө нь Swagger UI-ийн GET-д зориулсан өнгө. / бол хаяг — таны кодын @app.get("/") дээрх мөн тэр зураас. Root бол таны функцийн нэр (def root():), FastAPI түүнийг автоматаар товч тайлбар болгон авсан.

Гурвуулаа таны кодоос шууд уншигдсан. Та функцийнхээ нэрийг home гэж өөрчилбөл энэ хуудас дээр Home гэж гарч ирнэ. Хүсвэл туршаад үзээрэй — өөрчил, хадгал, хуудсаа шинэчил.

Endpoint-ийг нээж харах

Тэр мөр дээр товшино уу. Мөр доошоо задарч, дотор нь илүү дэлгэрэнгүй мэдээлэл гарч ирнэ.

Parameters гэсэн хэсэг харагдана. Одоохондоо тэнд No parameters гэж бичигдсэн байх болно, учир нь таны функц ямар ч параметр авдаггүй. Бүлэг 2-т та path parameter, query parameter нэмэх бөгөөд тэр үед энэ хэсэг дүүрч эхэлнэ.

Responses гэсэн хэсэг харагдана. Тэнд 200 гэсэн тоо, хажууд нь Successful Response гэсэн бичиг байна. Курс 2-оос та 200 гэдэг тоо "бүх зүйл сайн боллоо" гэсэн утгатайг мэднэ. FastAPI үүнийг үндсэн утга болгон авсан — таны функц асуудалгүй ажиллавал 200 буцаана. Бүлэг 3-т бид энэ тоог өөрчилж, өөр тоонууд нэмж сурна.

(Энд screenshot тавих боломжтой: endpoint задарсан байдал, Parameters болон Responses хэсгүүд харагдаж байгаа.)

Try it out — цэс дээрээс шууд захиалах

Одоо хамгийн сонирхолтой хэсэг. Баруун дээд буланд Try it out гэсэн товч байна. Түүн дээр товшино уу.

Хуудас бага зэрэг өөрчлөгдөж, доор нь том цэнхэр Execute товч гарч ирнэ. Түүн дээр товшино уу.

Хэдэн зуун миллисекундын дараа доор шинэ хэсэг гарч ирнэ. Тэнд дараах зүйлс байна.

Curl — таны хийсэн хүсэлтийг терминалын тушаал хэлбэрээр харуулж байна. Ойролцоогоор ийм:

curl -X 'GET' \
  'http://127.0.0.1:8000/' \
  -H 'accept: application/json'

Энэ нь та юу хийснийг өөр аргаар илэрхийлж байна. curl бол терминалаас HTTP хүсэлт илгээдэг эртний бөгөөд түгээмэл хэрэгсэл. Одоо ойлгох шаардлагагүй, гэхдээ ийм зүйл байдгийг мэдэж авахад илүүдэхгүй.

Request URL — яг ямар хаяг руу хандсаныг харуулна:

http://127.0.0.1:8000/

Server response — энэ бол хамгийн чухал хэсэг. Тэнд хоёр зүйл байна. Эхлээд Code гэсэн багана дор 200 гэсэн тоо. Дараа нь Response body доор таны JSON:

json

{
  "мэссэж": "Миний анхны API"
}

Энэ бол яг тэр өгөгдөл. Таны Python функц dictionary буцаасан, FastAPI түүнийг JSON болгосон, Swagger UI түүнийг цэвэрхэн хэлбэрээр танд харуулж байна.

Юу болсныг бүрэн ойлгох

Энд болсон зүйлийг тодорхой болгоё, учир нь энэ нь бүх сургалтын үндсэн эргэлт юм.

Та browser дээрх товч дарлаа. Тэр товч таны сервер рүү HTTP хүсэлт илгээв. Таны терминал дээр ажиллаж байгаа сервер тэр хүсэлтийг хүлээж авав. FastAPI хүсэлтийн хаягийг (/) харж, өөрийн бүртгэлээс тохирох функцийг (root) олж, дуудав. Функц dictionary буцаав. FastAPI түүнийг JSON болгож, 200 гэсэн статустай хамт буцаан илгээв. Swagger UI хүлээж авч, дэлгэц дээр харууллаа.

Энэ бүхэн секундын хэдэн зуутын дотор, таны компьютер дотор болсон. Гэхдээ энэ бол яг тэр процесс — дэлхийн хамгийн том компаниудын API-д ч яг ижилхэн зүйл болдог, зөвхөн хаяг нь илүү хол, ачаалал нь илүү их байдаг.

Хуудас хаанаас ирсэн бэ — /openapi.json

Дээд талд байсан /openapi.json холбоос дээр товшино уу. Эсвэл browser дээрээ шууд ийм хаяг нээнэ:

http://127.0.0.1:8000/openapi.json

Та том, төвөгтэй харагдах JSON харна. Ойролцоогоор ийм эхэлнэ:

json

{
  "openapi": "3.1.0",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Root",
        "operationId": "root__get",
        "responses": {
          "200": {
            "description": "Successful Response"
          }
        }
      }
    }
  }
}

Энэ бол таны API-ийн бүрэн техникийн тодорхойлолт, машины уншихад зориулсан хэлбэрээр. Энд таны бүх хаяг, method, параметр, хариу бичигдсэн байна. Энэ форматыг OpenAPI гэж нэрлэдэг бөгөөд энэ бол API-ийн дэлхийн стандарт юм.

Энэ файлыг та бичээгүй. FastAPI таны Python кодыг уншиж, decorator-уудыг тань харж, type hint-үүдийг тань шинжилж, түүнээс энэ бүхнийг автоматаар үүсгэсэн. Дараа нь Swagger UI энэ файлыг уншиж, таны харсан гоё хуудсыг зурсан.

Гурван түвшний гинжийг ойлгох нь чухал: таны код -> openapi.json -> /docs хуудас. Хамгийн доор таны бичсэн Python байна. Дунд нь стандарт тодорхойлолт. Дээр нь хүн харах интерфейс. Та зөвхөн доод түвшинг бичдэг; үлдсэн хоёр нь өөрөө үүсдэг.

Бүх сургалтын турш та энэ гинжийг ажиллахыг харна. Бүлэг 2-т та type hint нэмэхэд /docs дээр параметрийн төрөл гарч ирнэ. Бүлэг 4-т та Pydantic model бичихэд /docs дээр бүтэн маягт гарч ирнэ. Бүлэг 7-т та tag нэмэхэд /docs бүлэглэгдэнэ. Та ямар ч нэмэлт ажил хийхгүй — зөвхөн Python-оо сайн бичихэд л хангалттай.

/redoc — өөр төрх

FastAPI үнэндээ хоёр баримтжуулалтын хуудас өгдөг. Нөгөөг нь ийм хаягаар харна:

http://127.0.0.1:8000/redoc

Энэ бол ReDoc гэдэг өөр интерфейс. Ижил өгөгдөл (ижил openapi.json), гэхдээ өөр загвар: илүү намуун, унших зориулалттай, гурван баганатай.

Гол ялгаа нь: ReDoc дээр Try it out товч байхгүй. Энэ нь зөвхөн уншихад зориулагдсан. Тиймээс бид сургалтын турш голдуу /docs ашиглана — бидэнд туршилтын товч хэрэгтэй. Гэхдээ бодит компаниуд заримдаа гадны хэрэглэгчиддээ ReDoc-ыг илүү үздэг, учир нь энэ нь баримт бичиг шиг илүү харагддаг.

Энэ хуудас бол таны лаборатори

Одооноос эхлэн сургалтын турш дараах хэмнэл давтагдана. Та editor дээрээ шинэ endpoint бичнэ. Хадгална. Терминал өөрөө reload болно. Та /docs хуудсаа шинэчилнэ. Шинэ endpoint тань жагсаалт дээр гарч ирнэ. Та Try it out дарж, Execute дарж, хариугаа харна.

Энэ гурван товчийг та олон зуун удаа дарна. Тиймээс тэднийг сайн санаж авах нь зүйтэй: мөр дээр товшиж задлах, Try it out, Execute.

Энэ хуудас байхгүй байсан бол та endpoint бүрээ туршихын тулд эсвэл browser-ийн хаягийн мөрөнд гараар хаяг бичих (энэ нь зөвхөн GET-д ажилладаг), эсвэл requests кодоор жижиг скрипт бичих (тухай бүрд), эсвэл Postman гэх мэт тусдаа программ суулгах шаардлагатай болно. FastAPI танд эдгээрийг үнэгүй, автоматаар өгсөн.

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

Хуудас нээгдэхгүй байна

Browser дээр ийм зүйл гарвал:

This site can't be reached. 127.0.0.1 refused to connect.

Энэ нь маш энгийн шалтгаантай: сервер ажиллахгүй байна. Терминалаа шалгана уу. Ctrl+C дарж унтраасан байж магадгүй, эсвэл терминалын цонх хаагдсан байж магадгүй. Дахин асаана:

fastapi dev main.py

(venv) харагдаж байгаа эсэхийг эхлээд шалгаарай.

404 Not Found

Хэрэв /docs биш /doc (нэг үсэг дутуу) гэж бичвэл ийм хариу авна:

json

{
  "detail": "Not Found"
}

Энэ бол таны API-ийн хариу — "тийм хаяг байхгүй байна" гэж хэлж байна. Гоё хуудас биш, зүгээр л JSON. Энэ бол зөв, хүлээгдэж байсан зан төлөв. Бүлэг 3-т та энэ 404-ийг өөрөө үүсгэж сурна.

Шинэ endpoint /docs дээр харагдахгүй байна

Хэрэв та шинэ endpoint нэмээд /docs дээр харагдахгүй бол ихэвчлэн хоёр шалтгааны нэг:

Нэгд, файлаа хадгалаагүй. Ctrl+S дарна уу.

Хоёрт, browser хуучин хуудсаа санаж байна. Хатуу шинэчлэлт хийнэ үү (Ctrl+Shift+R эсвэл Ctrl+F5).

Өөрчлөлт харагдахгүй бол — терминал дээр reload болсныг шалгаарай. Терминал дээр шинэ мөр гарсан бол сервер тань шинэчлэгдсэн гэсэн үг, тэгвэл асуудал browser-т байна.

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

Хүсвэл кодынхоо функцийн нэрийг өөрчилж үзээрэй — def root(): гэснийг def welcome(): болгоод хадгална. /docs хуудсаа шинэчилээд endpoint-ийн нэр өөрчлөгдсөнийг ажиглаарай. Энэ жижиг туршилт нь "баримт бичиг код дээр тулгуурладаг" гэдгийг гар дээрээ мэдрүүлнэ.

Сонирхвол app = FastAPI() гэснийг ийм болгож үзээрэй:

python

app = FastAPI(title="Миний анхны API")

Хадгалаад /docs хуудсаа шинэчилээд дээд талын гарчиг өөрчлөгдсөнийг харна уу. Энэ бол баримтжуулалтаа тохируулах эхний алхам.

Товч дүгнэлт

• FastAPI таны кодоос автоматаар баримт бичиг үүсгэдэг — гараар бичих, шинэчлэх шаардлагагүй.

• /docs бол интерактив хуудас (Swagger UI): endpoint-үүдээ харах, Try it out дарж шууд туршиж болно.

• /redoc бол ижил өгөгдлийн өөр, зөвхөн уншихад зориулсан төрх.

• /openapi.json бол хоёуланг нь тэжээж буй машины уншихад зориулсан стандарт тодорхойлолт.

• Гинж нь: таны код -> openapi.json -> /docs хуудас. Та зөвхөн эхнийхийг бичнэ.

• Хуудас нээгдэхгүй бол сервер ажиллаж байгаа эсэхийг эхлээд шалгана.

Бүлэг 1 өндөрлөж байна. Та орчноо бэлдэж, серверээ асааж, өөрийн API-ийн эхний хариуг харлаа. Дараагийн бүлэгт бид жинхэнэ ажил эхлүүлнэ: path operation гэж юу болох, @app.get decorator доор яг юу болж байгаа, хаягтаа утга хэрхэн дамжуулах, хэрэглэгчээс параметр хэрхэн авахыг сурна. Тэнд Курс 2-ын decorator-ын мэдлэг тань бүрэн ажиллаж эхэлнэ.