Перші кроки¶

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

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

$ <font color="#4E9A06">readyapi</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 ReadyAPI app

 ╭─ <font color="#8AE234"><b>Importable ReadyAPI 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">╭────────── ReadyAPI 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>readyapi 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¶

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

"Схема"¶

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

API "схема"¶

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

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

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

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

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

OpenAPI і JSON Schema¶

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

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

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

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

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

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



...

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

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

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

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

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

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

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

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

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

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

Це буде головна точка для створення і взаємодії з 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)¶

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

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

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

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

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

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

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

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

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

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

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

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

Порада

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

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

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

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

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

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

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

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

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

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

Примітка

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

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

Python 3.8+

from readyapi import ReadyAPI

app = ReadyAPI()


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

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

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

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

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

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

Перші кроки¶

Перевірте¶

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

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

OpenAPI¶

"Схема"¶

API "схема"¶

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

OpenAPI і JSON Schema¶

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

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

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

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

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

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

Шлях (path)¶

Operation¶

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

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

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

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

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

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

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