Перші кроки¶

Найпростіший файл FastAPI може виглядати так:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Скопіюйте це до файлу main.py.

Запустіть сервер:

$ <font color="#4E9A06">fastapi</font> dev <u style="text-decoration-style:single">main.py</u>
<font color="#3465A4">INFO    </font> Using path <font color="#3465A4">main.py</font>
<font color="#3465A4">INFO    </font> Resolved absolute path <font color="#75507B">/home/user/code/awesomeapp/</font><font color="#AD7FA8">main.py</font>
<font color="#3465A4">INFO    </font> Searching for package file structure from directories with <font color="#3465A4">__init__.py</font> files
<font color="#3465A4">INFO    </font> Importing from <font color="#75507B">/home/user/code/</font><font color="#AD7FA8">awesomeapp</font>

 ╭─ <font color="#8AE234"><b>Python module file</b></font> ─╮
 │                      │
 │  🐍 main.py          │
 │                      │
 ╰──────────────────────╯

<font color="#3465A4">INFO    </font> Importing module <font color="#4E9A06">main</font>
<font color="#3465A4">INFO    </font> Found importable FastAPI app

 ╭─ <font color="#8AE234"><b>Importable FastAPI app</b></font> ─╮
 │                          │
 │  <span style="background-color:#272822"><font color="#FF4689">from</font></span><span style="background-color:#272822"><font color="#F8F8F2"> main </font></span><span style="background-color:#272822"><font color="#FF4689">import</font></span><span style="background-color:#272822"><font color="#F8F8F2"> app</font></span><span style="background-color:#272822">  </span>  │
 │                          │
 ╰──────────────────────────╯

<font color="#3465A4">INFO    </font> Using import string <font color="#8AE234"><b>main:app</b></font>

 <span style="background-color:#C4A000"><font color="#2E3436">╭────────── FastAPI CLI - Development mode ───────────╮</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  Serving at: http://127.0.0.1:8000                  │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  API docs: http://127.0.0.1:8000/docs               │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  Running in development mode, for production use:   │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│  </font></span><span style="background-color:#C4A000"><font color="#555753"><b>fastapi run</b></font></span><span style="background-color:#C4A000"><font color="#2E3436">                                        │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">│                                                     │</font></span>
 <span style="background-color:#C4A000"><font color="#2E3436">╰─────────────────────────────────────────────────────╯</font></span>

<font color="#4E9A06">INFO</font>:     Will watch for changes in these directories: [&apos;/home/user/code/awesomeapp&apos;]
<font color="#4E9A06">INFO</font>:     Uvicorn running on <b>http://127.0.0.1:8000</b> (Press CTRL+C to quit)
<font color="#4E9A06">INFO</font>:     Started reloader process [<font color="#34E2E2"><b>2265862</b></font>] using <font color="#34E2E2"><b>WatchFiles</b></font>
<font color="#4E9A06">INFO</font>:     Started server process [<font color="#06989A">2265873</font>]
<font color="#4E9A06">INFO</font>:     Waiting for application startup.
<font color="#4E9A06">INFO</font>:     Application startup complete.

У консолі буде рядок приблизно такого змісту:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Цей рядок показує URL, за яким додаток запускається на вашій локальній машині.

Перевірте¶

Відкрийте браузер та введіть адресу http://127.0.0.1:8000.

Ви побачите у відповідь таке повідомлення у форматі JSON:

{"message": "Hello World"}

Інтерактивна API документація¶

Перейдемо сюди http://127.0.0.1:8000/docs.

Ви побачите автоматичну інтерактивну API документацію (створену завдяки Swagger UI):

Swagger UI

Альтернативна API документація¶

Тепер перейдемо сюди http://127.0.0.1:8000/redoc.

Ви побачите альтернативну автоматичну документацію (створену завдяки ReDoc):

ReDoc

OpenAPI¶

FastAPI генерує "схему" з усім вашим API, використовуючи стандарт OpenAPI для визначення API.

"Схема"¶

"Схема" - це визначення або опис чогось. Це не код, який його реалізує, а просто абстрактний опис.

API "схема"¶

У цьому випадку, OpenAPI є специфікацією, яка визначає, як описати схему вашого API.

Це визначення схеми включає шляхи (paths) вашого API, можливі параметри, які вони приймають тощо.

"Схема" даних¶

Термін "схема" також може відноситися до структури даних, наприклад, JSON.

У цьому випадку це означає - атрибути JSON і типи даних, які вони мають тощо.

OpenAPI і JSON Schema¶

OpenAPI описує схему для вашого API. І ця схема включає визначення (або "схеми") даних, що надсилаються та отримуються вашим API за допомогою JSON Schema, стандарту для схем даних JSON.

Розглянемо `openapi.json`¶

Якщо вас цікавить, як виглядає вихідна схема OpenAPI, то FastAPI автоматично генерує JSON-схему з усіма описами API.

Ознайомитися можна за посиланням: http://127.0.0.1:8000/openapi.json.

Ви побачите приблизно такий JSON:

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {



...

Для чого потрібний OpenAPI¶

Схема OpenAPI є основою для обох систем інтерактивної документації.

Існують десятки альтернативних інструментів, заснованих на OpenAPI. Ви можете легко додати будь-який з них до FastAPI додатку.

Ви також можете використовувати OpenAPI для автоматичної генерації коду для клієнтів, які взаємодіють з API. Наприклад, для фронтенд-, мобільних або IoT-додатків

А тепер крок за кроком¶

Крок 1: імпортуємо `FastAPI`¶

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

FastAPI це клас у Python, який надає всю функціональність для API.

Технічні деталі

FastAPI це клас, який успадковується безпосередньо від Starlette.

Ви також можете використовувати всю функціональність Starlette у FastAPI.

Крок 2: створюємо екземпляр `FastAPI`¶

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Змінна app є екземпляром класу FastAPI.

Це буде головна точка для створення і взаємодії з API.

Крок 3: визначте операцію шляху (path operation)¶

Шлях (path)¶

"Шлях" це частина URL, яка йде одразу після символу /.

Отже, у такому URL, як:

https://example.com/items/foo

...шлях буде:

/items/foo

Додаткова інформація

"Шлях" (path) також зазвичай називають "ендпоінтом" (endpoint) або "маршрутом" (route).

При створенні API, "шлях" є основним способом розділення "завдань" і "ресурсів".

Operation¶

"Операція" (operation) тут означає один з "методів" HTTP.

Один з:

POST
GET
PUT
DELETE

...та більш екзотичних:

OPTIONS
HEAD
PATCH
TRACE

У HTTP-протоколі можна спілкуватися з кожним шляхом, використовуючи один (або кілька) з цих "методів".

При створенні API зазвичай використовуються конкретні методи HTTP для виконання певних дій.

Як правило, використовують:

POST: для створення даних.
GET: для читання даних.
PUT: для оновлення даних.
DELETE: для видалення даних.

В OpenAPI кожен HTTP метод називається "операція".

Ми також будемо дотримуватися цього терміна.

Визначте декоратор операції шляху (path operation decorator)¶

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Декоратор @app.get("/") вказує FastAPI, що функція нижче, відповідає за обробку запитів, які надходять до неї:

шлях /
використовуючи get операцію

@decorator Додаткова інформація

Синтаксис @something у Python називається "декоратором".

Ви розташовуєте його над функцією. Як гарний декоративний капелюх (мабуть, звідти походить термін).

"Декоратор" приймає функцію нижче і виконує з нею якусь дію.

У нашому випадку, цей декоратор повідомляє FastAPI, що функція нижче відповідає шляху / і операції get.

Це і є "декоратор операції шляху (path operation decorator)".

Можна також використовувати операції:

@app.post()
@app.put()
@app.delete()

І більш екзотичні:

@app.options()
@app.head()
@app.patch()
@app.trace()

Порада

Ви можете використовувати кожну операцію (HTTP-метод) на свій розсуд.

FastAPI не нав'язує жодного певного значення для кожного методу.

Наведена тут інформація є рекомендацією, а не обов'язковою вимогою.

Наприклад, під час використання GraphQL зазвичай усі дії виконуються тільки за допомогою POST операцій.

Крок 4: визначте функцію операції шляху (path operation function)¶

Ось "функція операції шляху":

шлях: це /.
операція: це get.
функція: це функція, яка знаходиться нижче "декоратора" (нижче @app.get("/")).

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Це звичайна функція Python.

FastAPI викликатиме її щоразу, коли отримає запит до URL із шляхом "/", використовуючи операцію GET.

У даному випадку це асинхронна функція.

Ви також можете визначити її як звичайну функцію замість async def:

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"message": "Hello World"}

Примітка

Якщо не знаєте в чому різниця, подивіться Конкурентність: "Поспішаєш?".

Крок 5: поверніть результат¶

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

Ви можете повернути dict, list, а також окремі значення str, int, ітд.

Також можна повернути моделі Pydantic (про це ви дізнаєтесь пізніше).

Існує багато інших об'єктів і моделей, які будуть автоматично конвертовані в JSON (зокрема ORM тощо). Спробуйте використати свої улюблені, велика ймовірність, що вони вже підтримуються.

Підіб'ємо підсумки¶

Імпортуємо FastAPI.
Створюємо екземпляр app.
Пишемо декоратор операції шляху як @app.get("/").
Пишемо функцію операції шляху; наприклад, def root(): ....
Запускаємо сервер у режимі розробки fastapi dev.